howone 0.1.19 → 0.1.22

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,101 @@
+# 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. **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.
+
+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.
+
+## 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/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>
 

package/templates/vite/.howone/skills/howone-sdk/{references/04-auth.md → 03-sdk/03-auth.md}

@@ -7,7 +7,7 @@ HowOne has two distinct auth layers:
 1. **Client-level auth** (`client.auth.*`) — low-level token management, login/logout redirects.  
 2. **HowOne Auth service** (`unifiedAuth`, standalone functions) — headless OTP and OAuth flows for building custom login UIs.
 
-For React auth UI, see `references/06-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
+For React auth UI, see `03-sdk/04-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
 
 ---
 
@@ -113,6 +113,15 @@ function useCurrentUser() {
 
 Use `sendEmailVerificationCode` → `loginWithEmailCode` to build a custom email login form.
 
+The SDK normalizes HowOne auth envelopes. Both of these backend response shapes are valid:
+
+```ts
+{ success: true, token: 'jwt...' }
+{ code: 0, data: { success: true, token: 'jwt...' } }
+```
+
+After normalization, read `result.success`, `result.token`, and `result.message` from the top level.
+
 ### Standalone functions (imported directly)
 
 ```ts
@@ -145,7 +154,7 @@ const loginResult = await loginWithEmailCode(
 
 if (loginResult.success && loginResult.token) {
   howone.auth.setToken(loginResult.token)
-  // Now client.auth.isAuthenticated() === true
+  // Persists the token and updates the active SDK client.
 }
 ```
 
@@ -423,6 +432,112 @@ async function checkToken(token: string) {
 }
 ```
 
+## Custom Login UI Pattern
+
+Use this when the app should show its own login page instead of redirecting to `/howone/auth`.
+
+### SDK setup
+
+```ts
+// src/lib/sdk.ts
+import { createClient } from '@howone/sdk'
+
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: { mode: 'managed' },
+})
+
+export default client
+```
+
+`managed` is still correct for most custom login pages because `howone.auth.setToken(token)`
+persists the token through the SDK auth store. Use `headless` only when an external auth
+provider owns token storage.
+
+### Provider setup
+
+```tsx
+<HowOneProvider auth="none" brand="hidden">
+  <App />
+</HowOneProvider>
+```
+
+`auth="none"` disables the provider redirect so the app can render its own login form.
+
+### App startup
+
+```tsx
+useEffect(() => {
+  let cancelled = false
+
+  howone.me()
+    .then((user) => {
+      if (!cancelled) setUser(user)
+    })
+    .catch(() => {
+      if (!cancelled) setUser(null)
+    })
+    .finally(() => {
+      if (!cancelled) setLoading(false)
+    })
+
+  return () => {
+    cancelled = true
+  }
+}, [])
+```
+
+Do not use `howone.auth.isAuthenticated()` as the first-load gate for protected UI. It is a
+synchronous token presence check. `howone.me()` verifies/restores the current session and is the
+right source of truth for initial render.
+
+### Login success
+
+```ts
+const result = await loginWithEmailCode(email, code)
+if (!result.success || !result.token) {
+  setError(result.message ?? 'Invalid code')
+  return
+}
+
+howone.auth.setToken(result.token)
+const user = await howone.me({ refresh: true })
+setUser(user)
+```
+
+Use the same pattern for phone OTP and OAuth popup results.
+
+### Logout
+
+```ts
+const token = howone.auth.getToken()
+if (token) await unifiedAuth.logout(token)
+howone.auth.logout()
+setUser(null)
+```
+
+`howone.auth.logout()` clears the SDK token store and active client token.
+
+## Headless External Auth Pattern
+
+Use `auth.mode = "headless"` only when another auth system owns the token lifecycle.
+
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: {
+    mode: 'headless',
+    getToken: async () => externalAuth.getJwt(),
+    tokenCacheMs: 30_000,
+  },
+})
+```
+
+Do not invent a second localStorage key for HowOne OTP/OAuth login. Use `howone.auth.setToken`
+unless the user explicitly asks to integrate an external auth provider.
+
 ---
 
 ## Logout
@@ -495,5 +610,7 @@ const client = createClient({
 |---|---|
 | Phone number without country code: `'13800138000'` | Use E.164: `'+8613800138000'` |
 | Using `loginWithEmailCode` without first calling `sendEmailVerificationCode` | Always send the code first |
-| Setting token manually when using `auth.mode: 'managed'` | Use `managed` mode which handles storage, or switch to `headless` |
+| Hand-writing a separate localStorage token key for HowOne OTP/OAuth | Use `howone.auth.setToken(token)` |
+| Using `auth.isAuthenticated()` to decide first render after refresh | Use `await howone.me()` |
+| Setting `HowOneProvider auth="required"` with a custom in-app login form | Use `auth="none"` so the provider does not redirect |
 | Calling `unifiedAuth.logout()` without the token argument | Pass `token`: `await unifiedAuth.logout(howone.auth.getToken()!)` |