howone 0.1.31 → 0.1.32

package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md

@@ -0,0 +1,123 @@
+# Backend Query Contracts
+
+Use this reference while designing entity query behavior: filters, sorts, pagination, indexes, and
+public constraints. It is backend-only; SDK query syntax belongs in `04-app-sdk/12-query-dsl-and-responses.md`.
+
+## Query Surface
+
+Every list/detail experience should be traceable to fields declared in the entity schema:
+
+| Need | Contract field |
+|---|---|
+| Filter by status/category/slug | `access.public.allowedFilters` for public reads; schema field exists |
+| Sort by date/rank/title | `access.public.allowedSorts` for public reads; `performance.allowedSorts` for app reads |
+| Fast owner history | owner-scoped index such as `["status", "updatedDate"]` |
+| Public one-record page | `public.read = "scoped"`, `requiredScopes`, low `maxLimit` |
+| Search | explicit product support; do not use as a replacement for scopes |
+
+## Filter Fields
+
+Only expose fields that are safe and stable.
+
+Good public filters:
+
+```json
+{
+  "allowedFilters": ["slug", "status", "category", "active"]
+}
+```
+
+Avoid public filters for:
+
+- private prompt text;
+- owner/user identifiers unless they are intentional route scopes;
+- internal moderation fields;
+- payment, token, or provider metadata;
+- high-cardinality fields that have no index and will be queried frequently.
+
+## Sort Fields
+
+Prefer predictable date or rank fields:
+
+```json
+{
+  "allowedSorts": ["publishedAt", "updatedDate"],
+  "defaultLimit": 20,
+  "maxLimit": 100
+}
+```
+
+Rules:
+
+- Public sort fields must be explicitly listed.
+- Sort fields used by large lists should have supporting indexes.
+- Do not expose arbitrary revenue, score, or internal ranking fields publicly unless the product
+  explicitly needs them.
+- Keep public `maxLimit` bounded.
+
+## Index Planning
+
+Design indexes from actual access patterns:
+
+```json
+{
+  "indexes": [
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
+    { "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" },
+    { "name": "public_slug_unique", "fields": ["slug"], "unique": true },
+    { "name": "public_status_published", "fields": ["status", "publishedAt"], "scope": "global" }
+  ]
+}
+```
+
+Use owner-scoped indexes for private per-user histories. Use global indexes for anonymous public
+lists. Use unique indexes for slug/share IDs when routes depend on uniqueness.
+
+## System Fields
+
+Generated records usually expose system fields such as:
+
+| Concept | Typical field |
+|---|---|
+| record id | `id` |
+| created date | `createdDate` |
+| updated date | `updatedDate` |
+| owner | `createdById` |
+| schema version id | `schemaVersionId` |
+| schema version number | `schemaVersionNumber` |
+
+Do not design app behavior around raw storage-only names unless the manifest or SDK reference
+requires that shape.
+
+## Pagination Defaults
+
+Every list contract should define practical limits:
+
+```json
+{
+  "performance": {
+    "defaultLimit": 20,
+    "maxLimit": 100,
+    "allowedSorts": ["updatedDate", "createdDate"]
+  }
+}
+```
+
+Public scoped detail pages should usually use:
+
+```json
+{
+  "defaultLimit": 1,
+  "maxLimit": 1
+}
+```
+
+## Query Contract Checklist
+
+- Every planned filter field exists in `properties`.
+- Public filters and sorts are explicitly allowlisted.
+- Owner/private histories have owner-scoped indexes.
+- Public lists have global indexes for common filter/sort combinations.
+- Scoped public pages include required scope fields and low limits.
+- List pages have pagination limits before SDK/UI code starts.
+- Query implementation is written only after `.howone/database/manifest.json` is synced.

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

@@ -1,77 +1,48 @@
-# AI Persistence Patterns
+# AI Persistence Entity 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.
+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.
 
-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.
+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 Rule
+## Core Boundary
 
 ```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.
+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 feature, ask:
+For every AI output field, decide:
 
-| Question | Persist? | Where |
+| Question | Persist? | Entity design |
 |---|---:|---|
-| 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:
+| 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 |
 
-- 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.
+## Pending-First Record Model
 
-For very fast, disposable AI actions, persistence may be unnecessary. Do not create an entity just
-because an AI workflow exists.
+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.
 
-## Status Fields
+Required contract pieces:
 
-Every persisted AI job/history entity should have a status field.
+- 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.
 
-Recommended:
+Status field:
 
 ```json
 {
@@ -83,31 +54,21 @@ Recommended:
 }
 ```
 
-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.
+- Do not infer completion only from `resultUrl`, `summary`, 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.
+- 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 Schema
+## Minimal Generation History Entity
 
-Use for image/text/report/music/video generation history.
+Use for image, text, report, music, video, or similar generation history.
 
 ```json
 {
   "name": "Generation",
   "type": "object",
-  "visibility": "private",
   "properties": {
     "prompt": { "type": "string" },
     "status": { "type": "string", "default": "pending" },
@@ -138,18 +99,17 @@ Use for image/text/report/music/video generation history.
 }
 ```
 
-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.
+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.
 
-## Analysis Report Schema
+## Structured Analysis Report Entity
 
-Use when AI returns a structured report that users browse later.
+Use when AI returns a report users browse later.
 
 ```json
 {
   "name": "AnalysisReport",
   "type": "object",
-  "visibility": "private",
   "properties": {
     "sourceTitle": { "type": "string" },
     "sourceUrl": { "type": ["string", "null"], "default": null },
@@ -165,50 +125,42 @@ Use when AI returns a structured report that users browse later.
   "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:
 
-```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(),
-})
+```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 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:
+Do not save the whole workflow envelope unless the product explicitly needs a private object field
+for audit/debug.
 
-- private `Generation` entity for user history and edits;
-- public or scoped `SharedGeneration` entity for anonymous viewing.
+## Public Share Split
 
-Why split:
+For public AI result pages, split private history from public share data:
 
-- 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.
+- private `Generation` stores prompts, failures, drafts, internal metadata, and user history;
+- public/scoped `SharedGeneration` stores only curated fields for anonymous viewing.
 
-Public scoped schema:
+Scoped public share entity:
 
 ```json
 {
   "name": "SharedGeneration",
   "type": "object",
-  "visibility": "public",
   "properties": {
     "shareId": {
       "type": "string",
@@ -241,93 +193,33 @@ Public scoped schema:
 }
 ```
 
-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
+Never make the main private generation history public just to support share pages.
 
-If the product has retry, store enough input fields to rebuild the workflow request.
+## Retry And Resume Fields
 
-Persist:
+If retry is part of the product, persist enough input fields to rebuild the workflow request:
 
-- 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.
+- prompt/source content reference;
+- selected style/mode/options;
+- uploaded file URLs or file IDs;
+- status and error message;
+- requested/completed timestamps.
 
 Do not persist:
 
-- temporary UI component state;
 - auth/session/token values;
+- raw uploaded browser bytes;
+- temporary component state;
 - 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.
+- hidden system prompts or internal prompts.
 
-## 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.
+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 implementing persistence, write the mapping explicitly:
+Before app implementation, write the mapping explicitly:
 
 ```text
 workflow input.prompt       -> Generation.prompt
@@ -339,34 +231,25 @@ 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.
+If a workflow output has no mapping, decide whether it is intentionally transient or 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 |
+| 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 if abuse constraints are handled |
+| Public submission to AI queue | public create only with anti-abuse constraints |
 
-Never make the main generation history public just to support a public share page. Create a scoped
-share entity or a curated public entity.
+## Persistence Checklist
 
-## 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. |
+- 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/03-ai-capabilities/01-ai-capability-architecture.md

@@ -16,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:
 
@@ -34,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
 ```
 
@@ -51,15 +50,14 @@ Use this flow for new AI features:
 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 `04-app-sdk/08-ai-manifest-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.
@@ -71,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 |
 
@@ -81,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
 
@@ -137,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.
@@ -202,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.