howone 0.1.22 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.22",
+  "version": "0.1.25",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/nextjs/lib/sdk.ts

@@ -18,6 +18,9 @@ export const entities = defineEntities({
 
 export const ai = defineAiActions({
   // Add generated AI action bindings here, for example:
+  // import { z } from "zod" and define Zod schemas before using defineAiAction.
+  // Do not paste JSON Schema objects from .howone/ai/manifest.json here directly.
+  // With outputSchema configured, howone.ai.<action>.run() returns the validated finalResult payload.
   // generateImage: defineAiAction("generateImage", {
   //   inputSchema: generateImageInputSchema,
   //   outputSchema: generateImageOutputSchema,

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

@@ -1,101 +1,215 @@
 # App Generation Architect
 
-Use this file to decide the HowOne app implementation path before reading low-level SDK or
-database references.
+Use this file before building or changing a HowOne generated app. It decides which platform tracks
+must be used and what order to execute them in.
 
-## Responsibility Split
+This is the planning layer. It should prevent the agent from jumping straight into UI code while
+missing schema, auth, AI, manifest, or SDK binding contracts.
 
-HowOne generated apps have three layers:
+## Platform Shape
 
-1. **Backend contract**: dynamic entities, access rules, indexes, schema versions, and synced
-   manifests.
-2. **SDK binding**: `src/lib/sdk.ts` converts manifests into typed entity and AI clients.
-3. **Frontend experience**: React/UI code calls the SDK and owns app-specific interaction design.
+HowOne generated apps have four product layers:
 
-Do not skip the binding layer. The UI should call `src/lib/sdk.ts`, not raw entity names guessed
-from the user prompt.
+| Layer | Source of truth | App code should do |
+|---|---|---|
+| Backend database | synced `.howone/database/manifest.json` | generate entity types/bindings and call SDK |
+| AI capabilities | synced `.howone/ai/manifest.json` + workflow status | generate AI action bindings and call SDK |
+| SDK runtime | `@howone/sdk` + `src/lib/sdk.ts` | centralize env/auth/entities/AI/upload |
+| Frontend app | user experience | own UI, state, feedback, forms, navigation |
 
-Core source-of-truth rule from the HowOne docs:
+The agent may propose schema/capability changes, but the validated/synced manifests drive code.
 
 ```text
-agent proposal != source of truth
-validated backend manifest = source of truth
-generated files = compiler/binding output
+user request -> architecture decision -> backend/AI contracts -> sync manifests -> sdk binding -> UI
 ```
 
-The agent proposes structured changes and writes app code. The runtime/schema tools validate,
-apply, version, and sync manifest facts.
+Do not skip the binding layer. UI code should import `howone` from `src/lib/sdk.ts`, not construct
+raw URLs or guessed entity/action names.
 
-## Choose Data Posture First
+## First Decision: What Surfaces Are Touched?
 
-Before designing schema or UI calls, classify the data:
+Classify the request before editing.
 
-| Posture | Backend Access | Frontend Read |
+| User request says | Touched surfaces | Required references |
 |---|---|---|
-| 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(...)` |
+| "store/save/history/list/my data" | database + SDK + UI | `02-database/`, `03-sdk/02-entity-operations.md` |
+| "login/account/my/private" | auth + database access | `03-sdk/03-auth.md`, `03-sdk/04-react-integration.md` |
+| "public page/share/link/landing/catalog" | public access + SDK public namespace | `02-database/03-data-access-patterns.md` |
+| "AI/generate/analyze/summarize/research/edit image/video/audio" | AI contract + workflow + SDK | `04-ai/` |
+| "upload file/image/audio/pdf" | upload + maybe AI URL input | `03-sdk/05-file-upload.md`, `04-ai/02-workflow-contract-rules.md` |
+| "change schema/add field/new table" | schema operations + manifest codegen | `02-database/02-schema-operations.md`, `01-architect/02-manifest-codegen.md` |
+| "frontend only" | SDK usage + UI | `03-sdk/01-client-setup.md` and relevant SDK docs |
 
-If the user says "my todos", "my notes", "per user", "login required", or "data isolation",
-default to private user data.
+If multiple surfaces are touched, read one reference from each surface before editing.
 
-## Backend Feature Workflow
+## Data Posture Decision
 
-When a request adds persistence or changes data shape:
+Choose data posture before schema and UI.
 
-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.
+| Product need | Access contract | SDK read |
+|---|---|---|
+| per-user private data | authenticated own, public none | `howone.entities.X.query.mine()` |
+| logged-in shared admin/team data | authenticated all, public none | `howone.entities.X.query()` |
+| anonymous public catalog/feed | authenticated all, public list | `howone.public.entities.X.query()` |
+| one public share/detail page | authenticated own/all, public scoped | `howone.public.entities.X.queryScoped()` |
+| anonymous form submission | authenticated all, public create scoped/any | `howone.public.entities.X.create()` |
+| AI generation history | authenticated own, public none | `runAiActionAndPersist()` + `query.mine()` |
+| AI public share | private history + public scoped share entity | two entities |
 
-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.
+Defaults:
+
+- "my" / "per user" / "private" -> authenticated own.
+- "landing page" / "blog" / "gallery" -> public list only if fields are safe.
+- "share link" / "QR" / "public result" -> public scoped, small `maxLimit`.
+- "AI history" -> private history entity; do not make it public just for sharing.
 
 ## Auth Decision
 
-Use hosted auth when the app just needs login:
+| Need | SDK config | Provider behavior |
+|---|---|---|
+| default HowOne login | `createClient({ projectId, env })` | hosted login |
+| custom designed login page using HowOne auth APIs | `auth: 'custom'`, `HowOneProvider auth="none"` | app owns login UI |
+| external identity provider/JWT | `auth: { mode: 'headless', adapter }` | adapter owns token/user |
+| public-only app | `auth: 'none'` | no auth guard |
+
+Rules:
 
-```tsx
-<HowOneProvider auth="required">
-  <App />
-</HowOneProvider>
-```
+- Keep the bottom-right HowOne `FloatingButton` by default unless explicitly hidden.
+- SDK must not add toast/overlay/login-page UI.
+- Use `client.me()` or `client.requireMe()` for first-load user resolution.
+- Do not use `auth.isAuthenticated()` as the only initial truth when user data must be loaded.
+
+## Backend Feature Workflow
+
+Use when persistence or schema changes are needed:
+
+1. Read `02-database/01-schema-design.md`.
+2. Read `02-database/02-schema-operations.md`.
+3. Inspect current schema state/manifest.
+4. Design complete entity contract: fields, required, access, indexes, presentation.
+5. Preview one complete schema patch.
+6. Apply the exact previewed patch if risk is acceptable.
+7. Sync schema artifacts from returned version.
+8. Read `.howone/database/manifest.json`.
+9. Update `src/lib/sdk.ts` from manifest using `01-architect/02-manifest-codegen.md`.
+10. Implement UI with `howone.entities.*` or `howone.public.entities.*`.
+11. Validate build/tests.
+
+Risk stops:
+
+- deleting entity/field;
+- making required field without default;
+- broadening public access;
+- enabling public write;
+- changing owner/public scope semantics.
+
+## AI Feature Workflow
+
+Use when AI capability/workflow is needed:
+
+1. Read `04-ai/01-ai-capability-architecture.md`.
+2. Read `04-ai/04-service-capability-catalog.md` to verify support.
+3. Pick a playbook from `04-ai/06-ai-feature-playbooks.md` when applicable.
+4. Design schemas with `04-ai/02-workflow-contract-rules.md`.
+5. Preview/apply AI capability patch.
+6. Sync `.howone/ai/manifest.json`.
+7. Submit external workflow create/update using `04-ai/05-workflow-operations.md`.
+8. Preserve returned `request_id`.
+9. Poll status until terminal; preserve `workflowConfigID` on success.
+10. Update `src/lib/sdk.ts` with `04-ai/03-ai-sdk-handoff.md`.
+11. Implement UI through `howone.ai.*`.
+12. If output persists, use `02-database/05-ai-persistence-patterns.md`.
+
+Do not build fake AI. If the required capability is unsupported, report the exact gap.
+
+## Manifest Codegen Workflow
+
+Run after database or AI sync:
+
+1. Read current `src/lib/sdk.ts`.
+2. Read synced manifests.
+3. Preserve existing exports and naming style.
+4. Generate/update:
+   - entity `Record/Create/Update` types;
+   - optional exported `*EntityDefinition` for guards;
+   - `client.entity<...>()` bindings;
+   - AI Zod schemas and `defineAiAction(...)`;
+   - composed `howone` export.
+5. Never write generated source under `.howone/`.
 
-Use custom in-app auth when the user asks for a designed login page or multiple login methods:
+## Common User Situations
 
-```tsx
-<HowOneProvider auth="none" brand="hidden">
-  <App />
-</HowOneProvider>
+### User asks for "just a frontend"
+
+Still check whether UI needs stored data, auth, upload, or AI. If it only renders static/local state,
+do not invent schema or workflow. If it saves anything, use database flow.
+
+### User asks for "AI app" but no persistence
+
+Design AI capability and SDK binding only. Keep results in app state. Do not create entities unless
+history, refresh resilience, user library, or share page is needed.
+
+### User asks for "AI app with history"
+
+Design AI first, then database:
+
+```text
+AI output contract -> Generation entity -> runAiActionAndPersist -> history query.mine()
 ```
 
-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 })`.
+Do not put history fields into workflow output unless the AI itself must generate them.
+
+### User asks for "public AI result"
+
+Use two entities:
+
+- private `Generation` for owner history and retry;
+- public scoped `SharedGeneration` for anonymous viewing.
+
+Do not expose private prompt/history broadly.
+
+### User asks for "latest/current/research"
+
+Use AI workflow with web search/crawling capability. If app also lists saved briefings, add entity
+persistence after output contract.
+
+### User asks to modify existing AI behavior
+
+If only behavior changes, use external workflow update with `workflowConfigID`.
+If input/output changes, update AI capability contract first, sync manifest, then update workflow
+and SDK bindings.
+
+### User asks to change schema used by UI
+
+Change backend schema first, sync, regenerate SDK, then update UI. Do not patch UI types from memory.
+
+### User asks for custom auth
+
+Use `auth: 'custom'` or headless `AuthAdapter`. App owns visible login UI. Keep SDK callbacks/data
+only.
+
+## Implementation Guardrails
 
-## Generated Binding Rules
+- Use `@howone/sdk` typed clients before `raw`.
+- Use `howone.raw` only when typed surface is missing.
+- Do not hardcode HowOne API URLs.
+- Do not pass owner fields for authenticated own records.
+- Do not import or create SDK toast APIs.
+- Do not remove HowOne floating logo unless explicitly requested.
+- Do not call AI workflows from render.
+- Do not persist workflow envelopes or UI-only fields.
+- Do not assume unavailable AI capabilities.
 
-- 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`.
+## Final Architecture Checklist
 
-## Common Failure Modes
+Before writing final code:
 
-- 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.
+- Data posture is explicit.
+- Auth mode is explicit.
+- Public access has filters/sorts/scopes/limits.
+- AI capability is supported by service catalog.
+- Workflow count follows one-feature rule or RAG exception.
+- Persistence is separate from AI workflow.
+- Manifests are synced before SDK codegen.
+- `src/lib/sdk.ts` is the only app SDK entrypoint.
+- UI owns visible states and feedback.

package/templates/vite/.howone/skills/howone-sdk/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`
@@ -249,6 +260,8 @@ import {
   defineAiAction,
   defineAiActions,
   defineEntities,
+  runAiActionAndPersist,
+  type EntityDefinition,
   type EntityRecord,
   withAiActions,
   withEntities,
@@ -293,6 +306,41 @@ export type CommentCreate = {
 }
 export type CommentUpdate = Partial<CommentCreate>
 
+export const storyEntityDefinition = {
+  name: 'Story',
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    content: { type: 'string' },
+    authorId: { type: 'string' },
+    status: { type: 'string', enum: ['draft', 'published', 'archived'] },
+    wordCount: { type: 'integer' },
+    tags: { type: 'array', items: { type: 'string' } },
+    coverUrl: { type: 'string' },
+  },
+  required: ['title', 'content', 'authorId', 'status', 'wordCount'],
+  access: {
+    authenticated: { read: 'own', create: 'own', update: 'own', delete: 'own' },
+    public: { read: 'none', create: 'none', update: 'none', delete: 'none' },
+  },
+} satisfies EntityDefinition
+
+export const commentEntityDefinition = {
+  name: 'Comment',
+  type: 'object',
+  properties: {
+    storyId: { type: 'string' },
+    authorId: { type: 'string' },
+    body: { type: 'string' },
+    likes: { type: 'integer' },
+  },
+  required: ['storyId', 'authorId', 'body'],
+  access: {
+    authenticated: { read: 'own', create: 'own', update: 'own', delete: 'own' },
+    public: { read: 'none', create: 'none', update: 'none', delete: 'none' },
+  },
+} satisfies EntityDefinition
+
 // ═══════════════════════════════════════════════════════════════
 // AI SCHEMAS & TYPES
 // ═══════════════════════════════════════════════════════════════
@@ -303,11 +351,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 +364,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 +389,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,
   }),
 })
@@ -366,12 +414,17 @@ export default howone
 Before finalising generated code, verify:
 
 - [ ] Every entity from `.howone/database/manifest.json` has a `Record`, `Create`, and `Update` type
+- [ ] Entity definitions are exported as `*EntityDefinition` when app code needs payload/query guards
 - [ ] `Create` types are defined **explicitly** (not via `Omit`)
 - [ ] Create optionality accounts for `required`, `default`, `defaultValue`, `autoGenerate`, and nullable types
 - [ ] 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
@@ -408,20 +461,21 @@ export const entities = defineEntities({
 
 When the app generates data with AI and saves it to an entity:
 
-1. Read `.howone/ai/manifest.json` → determine AI output shape.
-2. Define entity fields that mirror the AI output fields.
-3. Add any app-specific metadata fields (status, userId, createdAt, etc.).
-4. Generate the entity type, then the AI action binding.
+1. Read `.howone/ai/manifest.json` to know the typed AI output.
+2. Decide which output fields are durable product fields.
+3. Add app-specific persistence fields such as `status`, `errorMessage`, `requestedAt`,
+   `completedAt`, source URLs, prompt/options, or share state.
+4. Define/update the entity schema from product persistence needs, not by blindly copying
+   `outputSchema`.
+5. Generate entity types and AI action bindings from synced manifests.
+6. Use `runAiActionAndPersist()` for history-style products.
 
 ```ts
 // AI generates: { title: string, content: string, summary: string }
 // 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,
@@ -432,3 +486,24 @@ async function generateAndSave(input: GenerateStoryInput, authorId: string) {
   })
 }
 ```
+
+History-style generation should create a pending record before running AI:
+
+```ts
+await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input,
+  createPending: (input) => ({
+    prompt: input.topic,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+  }),
+  run: (input) => howone.ai.generateStory.run(input),
+  mapCompleted: ({ output }) => ({
+    status: 'completed',
+    title: output.title,
+    content: output.content,
+    completedAt: new Date().toISOString(),
+  }),
+})
+```