howone 0.1.31 → 0.1.32

package/templates/vite/.howone/skills/howone/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/03-ai-capabilities/04-workflow-operations.md

@@ -1,256 +1,141 @@
 # Workflow Operations
 
-Use this reference when submitting or checking external workflow create/update 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.
 
-Source: `docs/ai-worlfow-guide-schema.md`.
+## Current Tool Contract
 
-## Endpoints
+Do not hand-build raw workflow HTTP requests in generated app work. Use `external-ai-capability`
+after `.howone/ai/manifest.json` has been synced.
 
-| Purpose | Method | Path |
-|---|---|---|
-| Submit create/update operations | `POST` | `/workflow/{project_short_id}/operate` |
-| Check operation status | `GET` | `/workflow/status_check/{request_id}` |
+The tool performs:
 
-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": {}
-}
+```text
+POST /workflows
+GET  /jobs/{job_id}
 ```
 
-Field rules:
+The tool reads the synced manifest and submits operations for selected capabilities.
 
-| 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. |
+## Create
 
-Do not hand-copy stale schemas. Submit from synced `.howone/ai/manifest.json` whenever possible.
+Use create when the capability has a synced manifest entry and no external implementation has been
+submitted for its current `workflowId`.
 
-## Create Request
+Tool input:
 
 ```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": {}
-    }
-  ]
+  "cwd": "<app-root>",
+  "capabilityNames": ["summarizeDocument"]
 }
 ```
 
-Create response:
+Tool behavior:
 
-```json
-{
-  "request_ids": [
-    {
-      "request_id": "req_abc123",
-      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
-      "workflow_config_id": null,
-      "operation_type": "generate"
-    }
-  ]
-}
+```text
+config_id = manifest.capabilities[].workflowId
+mode      = create
+capability = synced manifest capability contract
 ```
 
-Store every `request_id`.
+Do not generate a second UUID for create. The AI capability design/sync path already produced the
+manifest `workflowId`.
+
+## Update
 
-## Update Request
+Use update when the external implementation exists and the user asks to change workflow behavior or
+to regenerate implementation for a changed contract.
 
-Use update when the external workflow implementation already exists.
+Tool input:
 
 ```json
 {
-  "operations": [
+  "cwd": "<app-root>",
+  "updates": [
     {
-      "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": {}
+      "capabilityName": "summarizeDocument",
+      "updatePrompt": "Support concise bullet-point summaries when the user asks for bullet format."
     }
   ]
 }
 ```
 
-Update response has `operation_type: "edit"`.
-
-## Status Polling
+Tool behavior:
 
 ```text
-POST /workflow/{project_short_id}/operate
-  -> request_ids[]
-
-GET /workflow/status_check/{request_id}
-  -> queued/running/completed/failed
+previous config = current manifest capability.workflowId
+new config      = freshly generated UUID
+mode            = update
+manifest        = rewritten so capability.workflowId is the fresh UUID
 ```
 
-Poll every 2-5 seconds until terminal.
+After update, re-read `.howone/ai/manifest.json`. The new manifest `workflowId` is the value used by
+SDK bindings and future execution.
 
-Status values:
+Do not pass stale `workflowConfigID` values from old docs or older status payloads. The current
+tool owns config rotation and manifest write-back.
 
-| 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 |
+## Selection Rules
 
-Completed success:
+- `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.
 
-```json
-{
-  "success": true,
-  "jobId": "req_abc123",
-  "status": "completed",
-  "payload": {
-    "success": true,
-    "workflow_details": {
-      "workflow_graph": {},
-      "new_workflow_config_id": "cfg_xyz789"
-    }
-  }
-}
-```
+## Status And Results
 
-Completed business failure:
+The tool may return immediately when a host poller is available. Preserve:
 
-```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..."
-  }
-}
-```
+- `jobId`;
+- `taskId` / `requestId` when present;
+- `submittedConfigId`;
+- `previousConfigId` for updates;
+- `manifestUpdates` mapping old workflow IDs to new workflow IDs.
 
-System failure:
+Terminal result meaning:
 
-```json
-{
-  "success": true,
-  "status": "failed",
-  "payload": {
-    "success": false,
-    "display_error_message": "Service temporarily unavailable.",
-    "full_error_message": "Timeout after 120s waiting for LLM response."
-  }
-}
+| 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
 ```
 
-On success, persist:
+Schema-changing AI update:
 
-- `request_id`;
-- `workflowId`;
-- `new_workflow_config_id`;
-- capability name;
-- mode;
-- any status/error useful for future update.
+```text
+ai-capability-design apply_capability_patch
+sync_ai_artifacts
+external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
+read .howone/ai/manifest.json
+```
 
-## Agent Handoff Notes
+Behavior-only update:
 
-When another tool/layer owns submission:
+```text
+external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
+read .howone/ai/manifest.json
+```
 
-- 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.
+SDK/code work happens after these steps and belongs to the SDK track.
 
-## Operation Checklist
+## 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.
+- 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.

package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md

@@ -1,7 +1,7 @@
 # AI Feature Playbooks
 
-Use this reference when turning a user request into concrete HowOne AI capabilities, database
-entities, and SDK calls.
+Use this reference when turning a user request into concrete HowOne AI capabilities and optional
+persistence entities. App-side SDK calls belong to `04-app-sdk/`.
 
 ## Playbook: Document Summary
 
@@ -47,11 +47,8 @@ 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 })
-```
+App implementation handoff: after sync and external workflow submit, read the SDK track before
+writing app-side AI runtime calls.
 
 ## Playbook: Image Generator
 
@@ -97,26 +94,8 @@ 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(),
-  }),
-})
-```
+App implementation handoff: if persistence is needed, finish the entity contract first, then read
+the SDK track for runtime action calls and persistence helper usage.
 
 ## Playbook: Image Editor
 
@@ -288,9 +267,9 @@ Rules:
 ## Feature Design Checklist
 
 - Choose one playbook or clearly combine compatible playbooks.
-- Verify capability exists in `04-service-capability-catalog.md`.
+- Verify capability exists in `03-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.
+- Generate SDK bindings only after manifest sync and external workflow submit.
 - Use app-owned UI for progress/errors.

package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md

@@ -77,7 +77,6 @@ client.public.raw: RawHttpClient
 client.schema.listDefinitions()
 client.schema.getDefinition(entityName)
 client.schema.operate(operation)
-client.schema.previewPatch(patch, { expectedVersionId, reason })
 client.schema.applyPatch(patch, { expectedVersionId, reason })
 client.schema.getState()
 client.schema.listVersions()
@@ -289,7 +288,7 @@ client.auth.logout()
 
 - Use `client.entities.*` / `howone.entities.*` for authenticated app data. The backend derives owner from the JWT; do not pass owner filters or owner fields.
 - Use `client.public.entities.*` / `howone.public.entities.*` for public landing pages, public article lists, scoped QR/profile pages, and public forms.
-- Use `client.schema.*` only for backend contract management: definitions, schema operations, schema patch preview/apply, versions, and restore.
+- Use `client.schema.*` only for backend contract management: definitions, schema operations, schema patch apply, versions, and restore.
 - Use `client.raw.*` only for custom endpoints not covered by typed SDK methods.
 
 ---

package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md

@@ -27,8 +27,8 @@ Correct sequence:
 1. `ai-capability-design` — design the capability contract
 2. `sync_ai_artifacts` — sync manifest to disk
 3. `external-ai-capability` — submit workflow create/update to EAX from the synced manifest
-4. Workflow status/background-task layer confirms readiness and captures `workflowConfigID` for future edits
-5. Read `.howone/ai/manifest.json` → write `src/lib/sdk.ts` with `workflowId`
+4. Re-read `.howone/ai/manifest.json`; update may have rotated `workflowId`
+5. Write `src/lib/sdk.ts` with the current manifest `workflowId`
 
 Building without errors does **not** mean the AI workflow binding is correct. A missing `workflowId` causes a runtime UUID error at the EAX execution call.
 

package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md

@@ -217,12 +217,13 @@ Do not ask the workflow to write records. Do not pass owner fields for authentic
 When changing external workflow behavior later:
 
 1. If schema changes, update AI capability contract first and sync manifest.
-2. Use `workflowConfigID` from a completed status result.
-3. Submit update with `capabilityName`, `workflowConfigID`, and `updatePrompt`.
-4. Preserve the new status result and config ID if it changes.
-5. Regenerate SDK only if manifest contract changed.
+2. Submit update through `external-ai-capability` with `updates: [{ capabilityName, updatePrompt }]`.
+3. Re-read `.howone/ai/manifest.json`; update may rotate `workflowId` to a fresh config UUID.
+4. Regenerate SDK bindings whenever the manifest `workflowId`, input schema, or output schema changed.
+5. Behavior-only updates still require checking the manifest before deciding SDK is unchanged.
 
-`workflowConfigID` is not `workflowId`.
+The SDK does not use old `workflowConfigID` status values. It binds to the current manifest
+`workflowId`, which is the EAX config id used in execution URLs.
 
 ## Handoff Checklist
 

package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md

@@ -61,7 +61,7 @@ Do not add one-off flags when an adapter/callback can express the behavior.
 | Auth | token source, session state, login/logout destination policy, hosted HowOne defaults | login page visuals, account menu, loading states, auth error UI |
 | React provider | context, auth callbacks, optional bottom-right HowOne `FloatingButton` logo | layout, toasts, overlays, route components, theme system |
 | Entities | typed CRUD/query clients, public/private routing, payload normalization | forms, list rendering, optimistic UI, field-level UX |
-| Schema | definition operations, preview/apply/version/restore calls | migration approval UI, admin experience |
+| Schema | definition operations, apply/version/restore calls | migration approval UI, admin experience |
 | Entity contract utilities | payload whitelisting, public query guardrail validation, structured validation issues | deciding product copy, rendering validation errors |
 | AI workflows | run/stream/events, Zod validation, workflowId binding | progress UI, result rendering, failure surfaces |
 | AI persistence | pending-first orchestration helper, state callbacks, completed/failed mapping hook | choosing schema fields, retry UX, visible state UI |

package/templates/vite/.howone/skills/howone/{02-entity-schema/03-data-access-patterns.md → 04-app-sdk/11-entity-data-access-patterns.md}

@@ -1,10 +1,10 @@
-# Data Access Patterns
+# Entity Data Access Patterns (App SDK)
 
 Use this reference to connect backend `access` design to frontend SDK calls. It answers:
 **which namespace should the app call, which filters are legal, and what must not be persisted?**
 
-For schema design, read `01-schema-design.md`. For query syntax details, read
-`04-query-dsl-and-responses.md`.
+For schema design, read `02-entity-schema/01-schema-design.md`. For query syntax details, read
+`12-query-dsl-and-responses.md`.
 
 ## Namespace Decision
 
@@ -14,7 +14,7 @@ For schema design, read `01-schema-design.md`. For query syntax details, read
 | Logged-in shared records | `howone.entities.Entity` | yes | `query`, `get`, CRUD |
 | Public list page | `howone.public.entities.Entity` | no | `query` |
 | Public scoped share/detail | `howone.public.entities.Entity` | no | `queryScoped`, `get` with scope options |
-| Schema tooling | `howone.schema` | yes | `previewPatch`, `applyPatch` |
+| Schema tooling | `howone.schema` | yes | `applyPatch`, versions, restore |
 | Low-level fallback | `howone.raw` / `howone.public.raw` | depends | only when typed method missing |
 
 Do not mix authenticated and public namespaces for the same page without a clear reason.

package/templates/vite/.howone/skills/howone/{02-entity-schema/04-query-dsl-and-responses.md → 04-app-sdk/12-query-dsl-and-responses.md}

@@ -1,4 +1,4 @@
-# Query DSL And Responses
+# Entity Query DSL And Responses (App SDK)
 
 Use this reference when implementing list/detail pages, filters, sorting, pagination, or response
 normalization for HowOne dynamic entities.