howone 0.1.23 → 0.1.25

package/package.json

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

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

@@ -1,126 +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. **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.
+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.
+
+## First Decision: What Surfaces Are Touched?
+
+Classify the request before editing.
+
+| User request says | Touched surfaces | Required references |
+|---|---|---|
+| "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 multiple surfaces are touched, read one reference from each surface before editing.
 
-## Choose Data Posture First
+## Data Posture Decision
 
-Before designing schema or UI calls, classify the data:
+Choose data posture before schema and UI.
 
-| Posture | Backend Access | Frontend Read |
+| Product need | Access contract | SDK 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(...)` |
+| 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 |
+
+Defaults:
 
-If the user says "my todos", "my notes", "per user", "login required", or "data isolation",
-default to private user data.
+- "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
+
+| 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:
+
+- 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
 
-When a request adds persistence or changes data shape:
+Use when persistence or schema changes are needed:
 
-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.
+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.
 
-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.
+Risk stops:
+
+- deleting entity/field;
+- making required field without default;
+- broadening public access;
+- enabling public write;
+- changing owner/public scope semantics.
 
 ## 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.
+Use when AI capability/workflow is needed:
 
-## Auth Decision
+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`.
 
-Use hosted auth when the app just needs login:
+Do not build fake AI. If the required capability is unsupported, report the exact gap.
 
-```tsx
-<HowOneProvider auth="required">
-  <App />
-</HowOneProvider>
-```
+## 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/`.
+
+## Common User Situations
 
-Use custom in-app auth when the user asks for a designed login page or multiple login methods:
+### User asks for "just a frontend"
 
-```tsx
-<HowOneProvider auth="none" brand="hidden">
-  <App />
-</HowOneProvider>
+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

@@ -260,6 +260,8 @@ import {
   defineAiAction,
   defineAiActions,
   defineEntities,
+  runAiActionAndPersist,
+  type EntityDefinition,
   type EntityRecord,
   withAiActions,
   withEntities,
@@ -304,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
 // ═══════════════════════════════════════════════════════════════
@@ -377,6 +414,7 @@ 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
@@ -423,10 +461,14 @@ 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 }
@@ -444,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(),
+  }),
+})
+```