howone 0.1.20 → 0.1.23

package/templates/vite/.howone/skills/hallmark/vercel.json

@@ -0,0 +1,6 @@
+{
+  "outputDirectory": "site",
+  "framework": null,
+  "buildCommand": null,
+  "installCommand": null
+}

package/templates/vite/.howone/skills/howone-sdk/01-architect/01-app-generation.md

@@ -0,0 +1,126 @@
+# App Generation Architect
+
+Use this file to decide the HowOne app implementation path before reading low-level SDK or
+database references.
+
+## Responsibility Split
+
+HowOne generated apps have three layers:
+
+1. **Backend contract**: dynamic entities, access rules, indexes, schema versions, and synced
+   manifests.
+2. **AI contract + workflow implementation**: AI capability contracts are versioned by HowOne;
+   external workflow create/update is submitted from synced AI manifests.
+3. **SDK binding**: `src/lib/sdk.ts` converts manifests into typed entity and AI clients.
+4. **Frontend experience**: React/UI code calls the SDK and owns app-specific interaction design.
+
+Do not skip the binding layer. The UI should call `src/lib/sdk.ts`, not raw entity names guessed
+from the user prompt.
+
+Core source-of-truth rule from the HowOne docs:
+
+```text
+agent proposal != source of truth
+validated backend manifest = source of truth
+generated files = compiler/binding output
+```
+
+The agent proposes structured changes and writes app code. The runtime/schema tools validate,
+apply, version, and sync manifest facts.
+
+## Choose Data Posture First
+
+Before designing schema or UI calls, classify the data:
+
+| Posture | Backend Access | Frontend Read |
+|---|---|---|
+| Private user data | `authenticated: own`, `public: none` | `howone.entities.Entity.query.mine(...)` |
+| Authenticated shared app data | `authenticated: all`, `public: none` | `howone.entities.Entity.query(...)` |
+| Public list data | `authenticated: all`, `public: list` | `howone.public.entities.Entity.query(...)` |
+| Public scoped share data | usually `authenticated: own`, `public: scoped` | `howone.public.entities.Entity.queryScoped(...)` |
+
+If the user says "my todos", "my notes", "per user", "login required", or "data isolation",
+default to private user data.
+
+## Backend Feature Workflow
+
+When a request adds persistence or changes data shape:
+
+1. Read `02-database/01-schema-design.md` and `02-database/02-schema-operations.md`.
+2. Inspect the current schema/manifest.
+3. Design one complete schema patch for the feature.
+4. Preview the schema patch.
+5. Apply the exact previewed operations if risk is acceptable.
+6. Sync schema artifacts using the returned `next.versionId`.
+7. Read `.howone/database/manifest.json`.
+8. Read `01-architect/02-manifest-codegen.md`.
+9. Update `src/lib/sdk.ts`.
+10. Read the needed SDK file, usually `03-sdk/02-entity-operations.md` and sometimes `03-sdk/03-auth.md`.
+11. Update the UI.
+12. Validate.
+
+Do not preview a patch and then execute different single operations. Related schema changes for
+one feature should be grouped into one preview/apply cycle.
+
+## AI Feature Workflow
+
+When a request adds an AI capability or changes an AI workflow:
+
+1. Read `04-ai/01-ai-capability-architecture.md` and
+   `04-ai/02-workflow-contract-rules.md`.
+2. Inspect current AI capability state.
+3. Design one complete AI capability patch for the feature.
+4. Preview the AI patch.
+5. Apply the exact previewed operations.
+6. Sync AI artifacts.
+7. Read `.howone/ai/manifest.json`.
+8. Submit external workflow create/update with `external-ai-capability`.
+9. Preserve returned request IDs for the status/background-task layer.
+10. Read `04-ai/03-ai-sdk-handoff.md`, `01-architect/02-manifest-codegen.md`, and
+    `03-sdk/07-ai-action-calls.md`.
+11. Update `src/lib/sdk.ts` from the synced manifest.
+12. Update the UI.
+13. Validate.
+
+If generated output must be saved, design the AI capability first. Then derive persistence entities
+from the synced AI `outputSchema`, plus only necessary request metadata.
+
+## Auth Decision
+
+Use hosted auth when the app just needs login:
+
+```tsx
+<HowOneProvider auth="required">
+  <App />
+</HowOneProvider>
+```
+
+Use custom in-app auth when the user asks for a designed login page or multiple login methods:
+
+```tsx
+<HowOneProvider auth="none" brand="hidden">
+  <App />
+</HowOneProvider>
+```
+
+Custom login must call `howone.auth.setToken(token)` after Email OTP, Phone OTP, Google, or
+GitHub succeeds, then verify the session with `await howone.me({ refresh: true })`.
+
+## Generated Binding Rules
+
+- Read manifests after sync, not before.
+- Preserve existing bindings unless the manifest changed.
+- Export explicit `Record`, `Create`, and `Update` types.
+- Do not include system fields in create/update payloads.
+- Do not infer public access from `visibility` alone; inspect `access.public`.
+
+## Common Failure Modes
+
+- Repeated login after refresh: app used `auth.isAuthenticated()` as first-load truth or stored
+  token outside SDK. Read `03-sdk/03-auth.md`.
+- Data is not isolated: app used `query()` instead of `query.mine()` for `authenticated.read =
+  "own"`, or wrote owner fields manually.
+- Public page 401/403: app used authenticated namespace for public content or schema does not
+  allow public access.
+- Generated types drift from backend: app edited `src/lib/sdk.ts` from memory instead of synced
+  manifest.

package/templates/vite/.howone/skills/howone-sdk/{references/08-manifest-codegen.md → 01-architect/02-manifest-codegen.md}

@@ -13,6 +13,11 @@ HowOne apps are driven by two backend-synced manifests:
 
 Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. The coding agent reads the manifests and writes `src/lib/sdk.ts`.
 
+For AI capabilities, external workflow create/update is submitted by `external-ai-capability` from
+the synced manifest. Do not duplicate AI schemas in app code beyond generated zod/type bindings.
+For workflow edits, `workflowConfigID` belongs to the external workflow operation; it is not an SDK
+binding field.
+
 ---
 
 ## Reading `.howone/database/manifest.json`
@@ -157,6 +162,7 @@ export type CommentUpdate = Partial<CommentCreate>
     {
       "id": "generateStory",
       "name": "Generate Story",
+      "workflowId": "d69ab648-2c00-4d94-928e-01bd7b2a5bb2",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -179,6 +185,7 @@ export type CommentUpdate = Partial<CommentCreate>
     {
       "id": "translateText",
       "name": "Translate Text",
+      "workflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -219,12 +226,12 @@ export const generateStoryInputSchema = z.object({
 })
 export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
 
-// Output type for manual unwrapping (do NOT put in defineAiAction as outputSchema)
-export type GenerateStoryOutput = {
-  title: string
-  content: string
-  summary?: string
-}
+export const generateStoryOutputSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  summary: z.string().optional(),
+})
+export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 
 // ── translateText ─────────────────────────────────────────────
 export const translateTextInputSchema = z.object({
@@ -235,6 +242,10 @@ export const translateTextInputSchema = z.object({
 export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
 ```
 
+Do not make required output fields optional to silence validation failures. Do not add
+`.passthrough()` as a workaround for EAX execution envelopes. `defineAiAction` validates the
+workflow `finalResult` payload when an `outputSchema` is configured.
+
 ---
 
 ## Full Generated `src/lib/sdk.ts`
@@ -303,11 +314,12 @@ export const generateStoryInputSchema = z.object({
   language: z.string().optional(),
 })
 export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
-export type GenerateStoryOutput = {
-  title: string
-  content: string
-  summary?: string
-}
+export const generateStoryOutputSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  summary: z.string().optional(),
+})
+export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 
 export const translateTextInputSchema = z.object({
   text: z.string(),
@@ -315,10 +327,6 @@ export const translateTextInputSchema = z.object({
   formality: z.enum(['formal', 'informal']).optional(),
 })
 export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
-export type TranslateTextOutput = {
-  translatedText: string
-  detectedLang?: string
-}
 
 // ═══════════════════════════════════════════════════════════════
 // CLIENT
@@ -344,9 +352,12 @@ export const entities = defineEntities({
 
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
+    workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
     inputSchema: generateStoryInputSchema,
+    outputSchema: generateStoryOutputSchema,
   }),
   translateText: defineAiAction('translateText', {
+    workflowId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
     inputSchema: translateTextInputSchema,
   }),
 })
@@ -371,7 +382,11 @@ Before finalising generated code, verify:
 - [ ] System fields are not present in create/update input types
 - [ ] Public query/write types are generated only from `access.public.allowedFilters`, `allowedSorts`, `requiredScopes`, and write permissions
 - [ ] Every AI action from `.howone/ai/manifest.json` has an `inputSchema` zod object
+- [ ] Every AI action with manifest `outputSchema` has a matching zod `outputSchema`
+- [ ] Every AI action binding includes the exact manifest `workflowId`
 - [ ] Required input fields are not `.optional()` in zod
+- [ ] Required output fields are not `.optional()` in zod
+- [ ] AI output schemas do not use `.passthrough()` to hide execution-envelope mismatches
 - [ ] AI action names match the manifest `id` exactly (case-sensitive)
 - [ ] `createClient` uses `import.meta.env.*` only
 - [ ] `withEntities` is applied before `withAiActions` in the composition chain
@@ -418,10 +433,7 @@ When the app generates data with AI and saves it to an entity:
 // Save it to Story entity which adds: authorId, status, wordCount
 
 async function generateAndSave(input: GenerateStoryInput, authorId: string) {
-  const result = await howone.ai.generateStory.run(input)
-  if (!result.success) throw new Error(result.errors.join(', '))
-
-  const output = result.finalResult as GenerateStoryOutput
+  const output = await howone.ai.generateStory.run(input)
 
   return howone.entities.Story.create({
     title: output.title,

package/templates/vite/.howone/skills/howone-sdk/02-database/01-schema-design.md

@@ -0,0 +1,147 @@
+# Database Architecture Design
+
+Use this reference when designing or changing HowOne backend entity schemas. It summarizes
+the contract in `docs/dynamic-entity-architecture.zh.md` for app-building agents.
+
+This reference is for **backend entity design**. For schema tool flow, read
+`02-database/02-schema-operations.md`. For frontend read/write calls, read
+`02-database/03-data-access-patterns.md` and `03-sdk/02-entity-operations.md` after schema
+artifacts have been synced.
+
+## Core Model
+
+An entity is a versioned database contract, not a loose JSON form. Design all relevant parts:
+
+```ts
+type EntityContract = {
+  name: string
+  type: 'object'
+  description?: string
+  visibility: 'private' | 'public'
+  properties: Record<string, EntityField>
+  required?: string[]
+  access: {
+    authenticated?: AuthenticatedAccess
+    public?: PublicAccess
+  }
+  indexes?: EntityIndex[]
+  relations?: Record<string, EntityRelation>
+  presentation?: EntityPresentation
+  lifecycle?: EntityLifecycle
+  performance?: EntityPerformance
+}
+```
+
+Every schema change should preserve this mental split:
+
+- `properties` and `required` define payload validation.
+- `access` defines who can read/write and how ownership is derived.
+- `indexes` and `performance` define expected query paths.
+- `relations` defines valid `include` names.
+- `presentation` helps admin UI and SDK generation.
+- schema versions track the contract applied when future records are written.
+
+## Access Contract
+
+Every entity should explicitly define both authenticated and public access. Choose the data posture
+in `02-database/03-data-access-patterns.md`, then encode it in the `access` block here.
+
+## Field Design Rules
+
+- Entity and field names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+- Do not define system fields as business fields: `id`, `_id`, `created_date`, `updated_date`,
+  `created_by_id`, `schema_version_id`, `schema_version_number`, `is_sample`.
+- Required fields must be supplied on create unless the field has `default`, `defaultValue`, or
+  `autoGenerate`.
+- Use explicit enum fields for UI status values instead of free-form strings when choices are known.
+- Use ISO strings for date/datetime fields at the SDK boundary.
+- Complex JSON Schema validation may need frontend validation too; do not assume every nested
+  constraint is fully enforced by backend runtime.
+
+## Index and Performance Rules
+
+Add indexes for the query paths the UI will actually use:
+
+```json
+{
+  "indexes": [
+    {
+      "name": "owner_status_updated",
+      "fields": ["status", "updatedDate"],
+      "scope": "owner",
+      "order": { "updatedDate": "desc" }
+    }
+  ],
+  "performance": {
+    "defaultLimit": 20,
+    "maxLimit": 100,
+    "allowedSorts": ["createdDate", "updatedDate"]
+  }
+}
+```
+
+Guidelines:
+
+- Private user lists usually need owner-scoped indexes.
+- Public list pages need `access.public.allowedFilters` and `access.public.allowedSorts`.
+- `performance.allowedSorts` informs SDK/admin generation; public sort enforcement comes from
+  `access.public.allowedSorts`.
+
+## Todo Example
+
+For a personal Todo app:
+
+```json
+{
+  "name": "Todo",
+  "type": "object",
+  "description": "User-owned todo item",
+  "visibility": "private",
+  "properties": {
+    "text": { "type": "string" },
+    "completed": { "type": "boolean", "default": false }
+  },
+  "required": ["text"],
+  "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",
+      "order": { "updatedDate": "desc" }
+    }
+  ],
+  "performance": {
+    "defaultLimit": 50,
+    "maxLimit": 100,
+    "allowedSorts": ["createdDate", "updatedDate"]
+  },
+  "presentation": {
+    "titleField": "text",
+    "defaultSort": { "field": "updatedDate", "order": "desc" },
+    "listFields": ["text", "completed", "updatedDate"]
+  }
+}
+```
+
+Corresponding frontend read:
+
+```ts
+const result = await howone.entities.Todo.query.mine({
+  page: { number: 1, size: 50 },
+  orderBy: { updatedDate: 'desc' },
+})
+```

package/templates/vite/.howone/skills/howone-sdk/02-database/02-schema-operations.md

@@ -0,0 +1,96 @@
+# Schema Operations
+
+Use this reference when applying backend entity schema changes through HowOne runtime tools.
+
+## Source Of Truth
+
+```text
+agent proposal != source of truth
+validated backend manifest = source of truth
+synced .howone/database files = local copy of a backend version
+src/lib/sdk.ts = app binding generated from synced manifest
+```
+
+Do not hand-write `.howone/database` files. Sync them from a concrete backend schema version.
+
+## Preferred Patch Flow
+
+For feature-level schema work:
+
+1. Inspect current schema definitions or schema state.
+2. Design one complete patch containing all related operations.
+3. Preview the patch.
+4. Apply the exact same operations if risk is acceptable.
+5. Sync schema artifacts using the returned `next.versionId`.
+6. Read `.howone/database/manifest.json`.
+7. Update `src/lib/sdk.ts` from the manifest.
+8. Update frontend calls according to access.
+9. Validate.
+
+Do not preview a patch and then apply a different set of single operations.
+
+## Operation Types
+
+Supported schema operations:
+
+| Type | Purpose |
+|---|---|
+| `list_entities` | List current entity definitions. |
+| `get_entity` | Read one entity definition before modifying it. |
+| `create_entity` | Create a new entity contract. |
+| `update_entity` | Update entity metadata such as description, visibility, access, indexes, relations, presentation, lifecycle, performance. |
+| `delete_entity` | Soft or hard delete an entity definition. |
+| `add_field` | Add a new field. |
+| `update_field` | Patch an existing field definition. |
+| `delete_field` | Remove a field from schema, optionally from historical data. |
+| `set_field_required` | Add a field to top-level `required`. |
+| `unset_field_required` | Remove a field from top-level `required`. |
+
+## Payload Rules
+
+- `entityName` is required for every operation except `list_entities`.
+- `payload.properties` is required for `create_entity`.
+- `payload.required` must only contain fields that exist in `properties`.
+- `add_field` should use `{ fieldName, field, required }`.
+- `update_field` should use `{ fieldName, patch, required? }`.
+- `delete_field` should use `{ fieldName, removeFromData: false }` by default.
+- `required` belongs to the entity top level, not inside individual field definitions.
+
+## Risk Guardrails
+
+- Default entity deletion to soft delete.
+- Use hard delete only when the user explicitly asks.
+- Use `deleteData: true` only when the user explicitly asks to delete all records too.
+- Use `removeFromData: true` only after explicit confirmation.
+- Adding a required field to an existing entity should include a default when possible.
+- Changing a field type is high risk; inspect current schema and confirm intent before applying.
+- Schema restore creates a new restore version; it does not roll business data back.
+
+## Version Rules
+
+Schema versions manage entity definitions only. They do not roll back `entitydatashares`.
+
+After apply, use the returned version context:
+
+```json
+{
+  "next": {
+    "recommendedAction": "sync_schema_artifacts",
+    "versionId": "dbv_next"
+  }
+}
+```
+
+The synced manifest must be read before updating SDK bindings.
+
+## Narrow Edit Flow
+
+Single operations are acceptable for small explicit edits, such as "add priority to Todo":
+
+1. `get_entity`
+2. Check whether field already exists.
+3. Preview/apply one `add_field` patch or use the schema operation fallback.
+4. Sync artifacts.
+5. Update SDK/UI.
+
+For broader features, batch operations into one patch.

package/templates/vite/.howone/skills/howone-sdk/02-database/03-data-access-patterns.md

@@ -0,0 +1,172 @@
+# Data Access Patterns
+
+Use this reference to connect backend `access` design to frontend SDK calls.
+
+## Private Per-User Data
+
+Use for todos, notes, journals, saved generations, personal files, dashboards, and user-owned
+settings.
+
+Schema posture:
+
+```json
+{
+  "visibility": "private",
+  "access": {
+    "authenticated": {
+      "read": "own",
+      "create": "own",
+      "update": "own",
+      "delete": "own"
+    },
+    "public": {
+      "read": "none",
+      "create": "none",
+      "update": "none",
+      "delete": "none"
+    }
+  }
+}
+```
+
+Frontend calls:
+
+```ts
+const result = await howone.entities.Todo.query.mine({
+  page: { number: 1, size: 50 },
+  orderBy: { updatedDate: 'desc' },
+})
+```
+
+Rules:
+
+- Use `query.mine(...)` for list pages.
+- Use authenticated `create/update/delete`.
+- Do not pass owner fields such as `ownerId`, `created_by_id`, `createdById`,
+  `created_by_user_id`, or `puid`.
+
+## Authenticated Shared Data
+
+Use when logged-in users in the app should see shared records.
+
+Schema posture:
+
+```json
+{
+  "visibility": "private",
+  "access": {
+    "authenticated": {
+      "read": "all",
+      "create": "all",
+      "update": "all",
+      "delete": "all"
+    },
+    "public": {
+      "read": "none",
+      "create": "none",
+      "update": "none",
+      "delete": "none"
+    }
+  }
+}
+```
+
+Frontend calls:
+
+```ts
+const result = await howone.entities.Project.query({
+  page: { number: 1, size: 20 },
+  orderBy: { updatedDate: 'desc' },
+})
+```
+
+Use `query(...)`, not `query.mine(...)`.
+
+## Public Read-Only Content
+
+Use for public articles, templates, catalogs, profiles, or landing-page content.
+
+Schema posture:
+
+```json
+{
+  "visibility": "public",
+  "access": {
+    "authenticated": {
+      "read": "all",
+      "create": "all",
+      "update": "all",
+      "delete": "all"
+    },
+    "public": {
+      "read": "list",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "allowedFilters": ["slug", "status", "category"],
+      "allowedSorts": ["publishedAt", "updatedDate"],
+      "defaultLimit": 20,
+      "maxLimit": 100
+    }
+  }
+}
+```
+
+Frontend calls:
+
+```ts
+const result = await howone.public.entities.Article.query({
+  where: { status: 'published' },
+  page: { number: 1, size: 20 },
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
+Public query types should expose only allowed filters and allowed sorts.
+
+## Public Scoped Share Pages
+
+Use for public URLs that expose one owner-scoped record, such as QR pages or profile pages.
+
+Schema posture:
+
+```json
+{
+  "visibility": "public",
+  "access": {
+    "authenticated": {
+      "read": "own",
+      "create": "own",
+      "update": "own",
+      "delete": "own"
+    },
+    "public": {
+      "read": "scoped",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["ownerId", "slug"],
+      "allowedFilters": ["slug", "active"],
+      "allowedSorts": ["updatedDate"],
+      "defaultLimit": 1,
+      "maxLimit": 10
+    }
+  }
+}
+```
+
+Frontend calls:
+
+```ts
+const result = await howone.public.entities.QrProfile.queryScoped({
+  where: { ownerId, slug, active: true },
+  page: { number: 1, size: 1 },
+})
+```
+
+Rules:
+
+- Pass every `requiredScopes` field.
+- Do not use current user's `puid` as public owner scope unless schema explicitly stores that
+  value as the public scope.
+- Public scoped reads must stay inside `howone.public.entities.*`.

package/templates/vite/.howone/skills/howone-sdk/{references → 03-sdk}/01-client-setup.md

@@ -86,7 +86,7 @@ client.schema.restore(versionId, reason?)
 // AI action runner (low-level)
 client.ai: AiClient
 
-// HTTP utilities (low-level — see 07-raw-http.md)
+// HTTP utilities (low-level — see 03-sdk/06-raw-http.md)
 client.raw: RawHttpClient
 
 // File upload
@@ -134,7 +134,7 @@ const client = createClient({
 })
 
 // ── 2. Define entity types & bind ────────────────────────────
-// (see 02-entity-operations.md for full details)
+// (see 03-sdk/02-entity-operations.md for full details)
 export type NoteRecord = EntityRecord & { title: string; body: string }
 export type NoteCreate = { title: string; body: string }
 export type NoteUpdate = Partial<NoteCreate>
@@ -144,7 +144,7 @@ export const entities = defineEntities({
 })
 
 // ── 3. Define AI actions ─────────────────────────────────────
-// (see 03-ai-actions.md for full details)
+// (see 03-sdk/07-ai-action-calls.md for full details)
 export const summarizeInputSchema = z.object({ noteId: z.string() })
 export type SummarizeInput = z.infer<typeof summarizeInputSchema>