howone 0.2.3 → 0.2.6

package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md

@@ -108,6 +108,11 @@ Terminal result meaning:
 | `completed` | workflow operation completed |
 | `failed` / `canceled` / `timed_out` | report error and do not pretend workflow is ready |
 
+A non-terminal submission is not a legal completion or pause boundary for the Coding Agent. Do not
+end the run merely to wait for a host notification. Continue all implementation that does not need
+the promoted workflow ID, including UI structure, persistence, loading/error states, and other app
+logic. Defer only final workflow-ID binding and live execution verification until terminal success.
+
 ## Standard Flow
 
 New AI feature:
@@ -116,7 +121,8 @@ New AI feature:
 ai-capability-design apply_capability_patch
 sync_ai_artifacts
 external-ai-capability { cwd, capabilityNames }
-wait for terminal result
+continue independent app implementation; do not stop to wait
+terminal result
 sync_ai_artifacts
 read .howone/ai/manifest.json
 ```
@@ -127,7 +133,8 @@ Schema-changing AI update:
 ai-capability-design apply_capability_patch
 sync_ai_artifacts
 external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
-wait for terminal result
+continue independent app implementation; do not stop to wait
+terminal result
 sync_ai_artifacts
 read .howone/ai/manifest.json
 ```
@@ -136,13 +143,15 @@ Behavior-only update:
 
 ```text
 external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
-wait for terminal result
+continue independent app implementation; do not stop to wait
+terminal result
 sync_ai_artifacts
 read .howone/ai/manifest.json
 update SDK workflowId bindings from the newly synced manifest
 ```
 
-SDK/code work happens after these steps and belongs to the SDK track.
+Final workflow-ID SDK binding happens after terminal sync and belongs to the SDK track. Other app
+source work proceeds while the external job is pending.
 
 ## Checklist
 

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

@@ -1,329 +1,162 @@
 # Client Setup
 
-**Track:** `04-app-sdk/` — implement HowOne in the app from synced manifests; not schema/AI design.
+Use this track after synced manifests exist and before writing app code that imports
+`@howone/sdk`. Read [version-evidence.md](../../references/version-evidence.md) first when the installed
+SDK version is uncertain.
 
-## createClient
+## One client, one source of truth
 
-`createClient(opts: CreateClientOptions)` is the single factory for everything in the HowOne SDK. Call it once at module level and export the result (or the composed `howone` client).
-
-### CreateClientOptions — full type
-
-```ts
-type Environment = 'local' | 'dev' | 'prod'
-
-type CreateClientOptions = {
-  // ── Required ──────────────────────────────────────────────
-  projectId?: string           // Your HowOne project ID (set via VITE_HOWONE_PROJECT_ID)
-
-  // ── Environment ───────────────────────────────────────────
-  env?: Environment | string   // 'local' | 'dev' | 'prod'  (set via VITE_HOWONE_ENV)
-  apiUrl?: string              // Override the REST API base URL
-  aiUrl?: string               // Override the AI/SSE base URL
-
-  // ── Behaviour ─────────────────────────────────────────────
-  caseStyle?: 'camel' | 'snake' // Default: 'camel'
-  mode?: 'auto' | 'standalone' | 'embedded'
-
-  // ── Auth (one parameter for custom login) ─────────────────
-  auth?: 'custom' | 'hosted' | 'headless' | 'none' | {
-    mode?: 'custom' | 'hosted' | 'headless' | 'none' | 'managed'
-    loginPath?: string   // default '/login' when mode is 'custom'
-    logoutPath?: string
-    guard?: 'required' | 'optional' | 'none'
-    getToken?: () => Promise<string | null>
-    adapter?: AuthAdapter
-    tokenCacheMs?: number
-  }
-  loginPath?: string     // shorthand when auth is 'custom'
-  logoutPath?: string
-
-  // ── Limit-exceeded callbacks ───────────────────────────────
-  limitExceeded?: {
-    onLimitExceeded?: (context: LimitExceededContext) => void
-    showUpgradeToast?: boolean
-    upgradeUrl?: string
-  }
-
-  // ── Deprecated — do not use in new code ───────────────────
-  appId?: string        // Use projectId
-  baseUrl?: string      // Use apiUrl / aiUrl
-  apiBaseUrl?: string   // Use apiUrl
-  aiBaseUrl?: string    // Use aiUrl
-  authRequired?: boolean // Use auth.mode
-}
-```
-
-### What createClient returns
-
-```ts
-const client = createClient({ ... })
-
-client.projectId        // string — resolved project ID
-client.appId            // string — alias for projectId
-client.caseStyle        // 'camel' | 'snake'
-
-// Entity factory
-client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient
-
-// Typed entity map (populated via withEntities)
-client.entities: Record<string, EntityClient>
-
-// Public entity namespace (never sends Authorization)
-client.public.entity<TRecord, TPublicCreate, TPublicUpdate>(entityName: string): PublicEntityClient
-client.public.entities: Record<string, PublicEntityClient>
-client.public.raw: RawHttpClient
-
-// Schema contract/version client
-client.schema.listDefinitions()
-client.schema.getDefinition(entityName)
-client.schema.operate(operation)
-client.schema.applyPatch(patch, { expectedVersionId, reason })
-client.schema.getState()
-client.schema.listVersions()
-client.schema.getVersion(versionId)
-client.schema.restore(versionId, reason?)
-
-// AI action runner (low-level)
-client.ai: AiClient
-
-// HTTP utilities (low-level — see 04-app-sdk/06-raw-http.md)
-client.raw: RawHttpClient
-
-// File upload
-client.upload.file(file, options?)
-client.upload.image(file)
-client.upload.batch(options)
-
-// User profile
-client.me(options?)        // Promise<UserProfile | null>
-client.requireMe(options?) // Promise<UserProfile>  throws if unauthenticated
-client.session.user()      // alias for client.me()
-
-// Auth helpers (behavior driven by createClient auth mode)
-client.auth.mode          // 'custom' | 'hosted' | 'headless' | 'none'
-client.auth.loginPath     // e.g. '/login'
-client.auth.setToken(token: string | null)
-client.auth.getToken(): string | null
-client.auth.isAuthenticated(): boolean
-client.auth.login(returnUrl?: string)
-await client.auth.logout()
-await client.auth.clearSession({ redirect?: false | string })
-client.auth.subscribe((state) => { ... }) // auth state callback
-
-// URL utilities
-client.sanitizeUrl(opts?: { clearAll?: boolean; sensitiveParams?: string[] })
-```
-
----
-
-## Standard Vite Setup
+Create the client once at module scope in `src/lib/sdk.ts`. Use the same composed instance for
+entities, AI, uploads, auth, and raw requests. Do not create clients inside components or handlers.
 
 ```ts
 // src/lib/sdk.ts
 import {
   createClient,
-  defineAiAction,
   defineAiActions,
   defineEntities,
-  pickEntityPayload,
-  runAiActionAndPersist,
-  type EntityRecord,
   withAiActions,
   withEntities,
 } from '@howone/sdk'
-import { z } from 'zod'
 
-// ── 1. Create client ─────────────────────────────────────────
 const client = createClient({
   projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
   env: import.meta.env.VITE_HOWONE_ENV,
 })
 
-// ── 2. Define entity types & bind ────────────────────────────
-// (see 04-app-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>
-
 export const entities = defineEntities({
-  Note: client.entity<NoteRecord, NoteCreate, NoteUpdate>('Note'),
+  // Generated bindings go here; read 01-architect/02-manifest-codegen.md.
 })
+export const ai = defineAiActions({})
 
-// ── 3. Define AI actions ─────────────────────────────────────
-// (see 04-app-sdk/07-ai-action-calls.md for full details)
-export const summarizeInputSchema = z.object({ noteId: z.string() })
-export type SummarizeInput = z.infer<typeof summarizeInputSchema>
-
-export const ai = defineAiActions({
-  summarizeNote: defineAiAction('summarizeNote', {
-    inputSchema: summarizeInputSchema,
-  }),
-})
-
-// ── 4. Compose and export ────────────────────────────────────
 const howone = withAiActions(withEntities(client, entities), ai)
 export default howone
 ```
 
-SDK utility exports that generated apps may use:
+`projectId` is required. Missing or invalid Vite variables must fail loudly; do not add empty
+fallbacks such as `?? ''` or silently default the environment to production.
 
-| Utility | Use |
-|---|---|
-| `pickEntityPayload(definition, payload)` | Keep only schema-declared business fields before create/update. |
-| `validateEntityPayload(definition, payload)` | Return structured issues for unknown/system/ownership/missing required fields. |
-| `assertEntityPayload(definition, payload)` | Throw structured `EntityPayloadValidationError` before unsafe writes. |
-| `validatePublicEntityQuery(definition, options)` | Check public filters, sorts, scopes, and limits against `access.public`. |
-| `assertPublicEntityQuery(definition, options)` | Throw before generating an invalid public query. |
-| `runAiActionAndPersist(options)` | Standard pending-first AI execution + entity persistence helper. |
+## Environment-owned routing
 
----
+`env` selects the complete deployment target. The REST API, auth endpoints, uploads, and EAX
+workflow endpoint must use the same environment. EAX URLs are intentionally not configurable per
+request or through `createClient`:
 
-## Environment Variables
+| `env` | REST base | EAX workflow base |
+|---|---|---|
+| `local` | `http://localhost:3002/api` | `https://eax-backend-orchestrator-dev.fly.dev` |
+| `dev` | `https://api.howone.dev/api` | `https://eax-backend-orchestrator-dev.fly.dev` |
+| `prod` | `https://api.howone.ai/api` | `https://eax-backend-orchestrator-prod.fly.dev` |
 
-In Vite apps, these two env vars are mandatory:
+Never add `aiUrl`, `aiBaseUrl`, or an EAX URL environment variable. If a special deployment needs a
+different REST API, `apiUrl` is the only supported URL override; it does not change EAX routing.
 
-```
-VITE_HOWONE_PROJECT_ID=proj_xxxxxxxxxxxxxxxx
-VITE_HOWONE_ENV=prod
+The selected values are inspectable without guessing:
+
+```ts
+howone.runtime.environment // 'local' | 'dev' | 'prod'
+howone.runtime.apiBaseUrl
+howone.runtime.aiBaseUrl
+howone.runtime.authRoot
+howone.runtime.authCookieRoot
 ```
 
-Rules:
-- **Do not** add `?? 'prod'` or `?? ''` fallbacks. Missing env vars should surface as misconfiguration errors.
-- **Do not** hardcode project IDs in source. Use the env var.
-- `env` accepts `'local'`, `'dev'`, or `'prod'`. **Auth OTP/OAuth, entities, AI, and uploads all use this same env.**
-- Import `src/lib/sdk.ts` before calling `loginWithEmailCode` / `unifiedAuth` so env is pinned (otherwise auth defaults to prod APIs).
+`howone.runtime` is immutable. A second client created later cannot retarget an existing client's
+requests. Prefer one client per app; if tests create several, assert each client's runtime.
 
-| `env` | API base | Auth API example |
-|-------|----------|------------------|
-| `local` | `http://localhost:3002/api` | `http://localhost:3002/api/auth/email/send-code` |
-| `dev` | `https://api.howone.dev/api` | `https://api.howone.dev/api/auth/email/send-code` |
-| `prod` | `https://api.howone.ai/api` | `https://api.howone.ai/api/auth/email/send-code` |
+## Options that matter
 
----
+```ts
+type CreateClientOptions = {
+  projectId?: string
+  env?: 'local' | 'dev' | 'prod' | string
+  apiUrl?: string                 // REST-only exceptional override
+  apiBaseUrl?: string              // deprecated alias for apiUrl
+  appId?: string                  // deprecated alias for projectId
+  caseStyle?: 'camel' | 'snake'   // default 'camel'
+  caseDepth?: 'top-level' | 'deep' // default 'top-level'
+  auth?: 'hosted' | 'custom' | 'headless' | 'none' | {
+    mode?: 'hosted' | 'custom' | 'headless' | 'none'
+    guard?: 'required' | 'optional' | 'none'
+    loginPath?: string
+    logoutPath?: string
+    getToken?: () => Promise<string | null>
+    adapter?: AuthAdapter
+    tokenCacheMs?: number
+  }
+  loginPath?: string
+  logoutPath?: string
+  authRequired?: boolean             // deprecated compatibility alias
+  limitExceeded?: LimitExceededHandlerOptions
+}
+```
 
-## Auth Modes
+Do not use the removed `mode: 'auto' | 'standalone' | 'embedded'` option. That was not a runtime
+behavior switch. Authentication mode belongs under `auth.mode` and means hosted/custom/headless/none.
 
-See `04-app-sdk/03-auth.md` for the full custom-login playbook.
+## Authentication posture
 
 ```ts
-// Default — HowOne hosted login (howone.dev / howone.ai)
+// Hosted login (default): Provider inherits a required guard.
 createClient({ projectId, env })
 
-// Custom in-app login page; auth APIs still HowOne
+// App-owned login page using HowOne auth APIs.
 createClient({ projectId, env, auth: 'custom', loginPath: '/login' })
 
-// Headless — external JWT provider
+// External identity provider; adapter supplies a token.
 createClient({
   projectId,
   env,
   auth: {
     mode: 'headless',
     adapter: {
-      getToken: async () => externalAuth.getToken(),
+      getToken: () => externalAuth.getToken(),
       setToken: (token) => externalAuth.setToken(token),
-      login: ({ returnUrl } = {}) => router.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`),
-      logout: () => router.push('/'),
     },
-    tokenCacheMs: 60_000,
   },
 })
 
-// None — public app, no auth
+// Deliberately public app.
 createClient({ projectId, env, auth: 'none' })
 ```
 
----
+`HowOneProvider` receives `client={howone}` and derives its default route guard from
+`client.auth.guard`. Override `auth="required|optional|none"` only when the UI intentionally needs
+a different guard. Do not configure auth once on the client and independently guess it on the
+Provider.
 
-## Multi-environment Setup
+## Compose manifest bindings
 
-```ts
-// src/lib/sdk.ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  // Override URLs only for special deployments
-  // apiUrl: import.meta.env.VITE_HOWONE_API_URL,
-  // aiUrl: import.meta.env.VITE_HOWONE_AI_URL,
-})
-```
-
----
-
-## UserProfile Type
+Use contract wrappers for generated entities and actions. Public bindings are a separate namespace;
+never call an authenticated entity client from a public page just because the entity name matches.
 
 ```ts
-type UserProfile = {
-  id: string
-  userId?: string
-  puid?: string
-  email?: string
-  name?: string
-  avatarUrl?: string
-  appId?: string
-  roles?: string[]
-  metadata?: Record<string, unknown>
-}
-
-// Usage
-const me = await client.me()           // null if not logged in
-const me = await client.requireMe()    // throws HowOneAuthError if not logged in
-
-// Check auth state programmatically
-const isLoggedIn = client.auth.isAuthenticated()
-const token = client.auth.getToken()
-
-// Manually set a token (e.g. after custom login flow)
-client.auth.setToken(jwtToken)
-
-// Trigger login redirect
-client.auth.login('/dashboard') // optional return path
-
-// Logout
-client.auth.logout()
+const howone = withAiActions(
+  withPublicEntities(
+    withEntities(client, entities),
+    publicEntities,
+  ),
+  ai,
+)
 ```
 
----
-
-## Client Namespace Rules
-
-- 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 apply, versions, and restore.
-- Use `client.raw.*` only for custom endpoints not covered by typed SDK methods.
-
----
-
-## HowOneAuthError
+The exact generated composition belongs in `01-architect/02-manifest-codegen.md`.
 
-```ts
-import { HowOneAuthError } from '@howone/sdk'
-
-try {
-  const user = await client.requireMe()
-} catch (err) {
-  if (err instanceof HowOneAuthError) {
-    // err.code === 'UNAUTHENTICATED'
-    client.auth.login()
-  }
-}
-```
+## Runtime activation checklist
 
----
+- Keep `src/lib/sdk.ts` imported before rendering `HowOneProvider`.
+- Add a Provider whenever app code uses entities, AI, uploads, auth, session, or raw SDK requests.
+- Use `auth: 'none'` only for a deliberately public app or when the app owns its route guard.
+- Use real token acquisition for authenticated AI/entity/upload calls; do not substitute mock data.
+- Run `node .howone/skills/howone/scripts/verify-project.mjs` before typecheck/build.
 
-## LimitExceeded Handling
+## Common mistakes
 
-```ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  limitExceeded: {
-    showUpgradeToast: true,
-    upgradeUrl: 'https://howone.app/upgrade',
-    onLimitExceeded: (context) => {
-      console.error('Limit exceeded:', context.source, context.message)
-      // context.source: 'axios-response' | 'workflow-executor-sse' | ...
-      // context.status: HTTP status code (if available)
-    },
-  },
-})
-```
+| Mistake | Correct pattern |
+|---|---|
+| AI URL in `.env` or `createClient` | Set only `env`; EAX is environment-owned. |
+| `HowOneProvider` without the composed client | `<HowOneProvider client={howone}>`. |
+| Client created in a component | Module-level singleton in `src/lib/sdk.ts`. |
+| Using `apiUrl` to point at EAX | `apiUrl` is REST-only; EAX remains the env mapping. |
+| Passing a JSON Schema object to an AI action | Generate a Zod schema first. |
+| Calling `client.entities.Unknown` after strict codegen | Use `client.entity<T...>('Unknown')` only for an explicit, reviewed escape hatch. |