howone 0.1.23 → 0.1.26

package/templates/vite/.howone/skills/howone/03-sdk/08-extension-boundaries.md

@@ -0,0 +1,226 @@
+# SDK Extension Boundaries
+
+This reference defines the long-term shape of `@howone/sdk`. Use it whenever changing SDK APIs,
+adding new capabilities, or deciding whether behavior belongs in the SDK or in the generated app.
+
+## North Star
+
+The SDK is an AI-first runtime, not an app UI framework.
+
+It should provide:
+
+- stable defaults that work with almost no configuration;
+- typed clients for HowOne platform capabilities;
+- adapters for custom behavior;
+- callbacks/events for app UI;
+- predictable names that AI agents can reuse without guessing.
+
+It should not provide:
+
+- app-owned pages, modals, toasts, or business UI;
+- hardcoded app flows beyond HowOne platform defaults;
+- hidden persistence side effects;
+- provider-specific branches scattered through feature code.
+
+## Default + Adapter Rule
+
+Every platform capability should follow the same shape:
+
+```ts
+createClient({
+  projectId,
+  env,
+  auth: 'hosted', // default
+})
+```
+
+Advanced usage should opt into typed adapters:
+
+```ts
+createClient({
+  projectId,
+  env,
+  auth: {
+    mode: 'headless',
+    adapter: {
+      getToken: () => externalAuth.getToken(),
+      setToken: (token) => externalAuth.setToken(token),
+      login: ({ returnUrl }) => appRouter.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`),
+      logout: () => appRouter.push('/'),
+    },
+  },
+})
+```
+
+Do not add one-off flags when an adapter/callback can express the behavior.
+
+## Capability Boundaries
+
+| Capability | SDK owns | App owns |
+|---|---|---|
+| Auth | token source, session state, login/logout destination policy, hosted HowOne defaults | login page visuals, account menu, loading states, auth error UI |
+| React provider | context, auth callbacks, optional bottom-right HowOne `FloatingButton` logo | layout, toasts, overlays, route components, theme system |
+| Entities | typed CRUD/query clients, public/private routing, payload normalization | forms, list rendering, optimistic UI, field-level UX |
+| Schema | definition operations, preview/apply/version/restore calls | migration approval UI, admin experience |
+| Entity contract utilities | payload whitelisting, public query guardrail validation, structured validation issues | deciding product copy, rendering validation errors |
+| AI workflows | run/stream/events, Zod validation, workflowId binding | progress UI, result rendering, failure surfaces |
+| AI persistence | pending-first orchestration helper, state callbacks, completed/failed mapping hook | choosing schema fields, retry UX, visible state UI |
+| Upload | file/image/batch helpers and callbacks | picker UI, previews, validation copy, uploaded-file placement |
+| Raw HTTP | low-level escape hatch | choosing it only when typed SDK surface does not exist |
+
+## React Provider Boundary
+
+`HowOneProvider` may render the HowOne bottom-right logo via `FloatingButton`. This is platform
+branding and should remain visible by default.
+
+It must not render:
+
+- toast notifications;
+- redirect overlays;
+- login/register forms;
+- payment dialogs;
+- app theme wrappers;
+- app-specific navigation.
+
+Use callbacks instead:
+
+```tsx
+<HowOneProvider
+  auth="required"
+  brand="visible"
+  onAuthRedirect={({ mode, returnUrl }) => {
+    setAuthUi({ redirecting: true, mode, returnUrl })
+  }}
+  onAuthStateChange={(state) => {
+    setCurrentUser(state.user)
+  }}
+>
+  <App />
+</HowOneProvider>
+```
+
+Hide the logo only when explicitly requested:
+
+```tsx
+<HowOneProvider brand="hidden" />
+<HowOneProvider showBrandButton={false} />
+```
+
+## UI Feedback Rule
+
+Do not add `ClayxToast`, `toast`, or any visible notification API to `@howone/sdk`.
+
+Generated apps should write their own UI from SDK results:
+
+```ts
+setStatus({ type: 'loading', message: 'Generating...' })
+
+try {
+  const output = await howone.ai.generateImage.run({ prompt })
+  setStatus({ type: 'success', message: 'Done', output })
+} catch (error) {
+  setStatus({
+    type: 'error',
+    message: error instanceof Error ? error.message : 'Generation failed',
+  })
+}
+```
+
+For streaming workflows, use callbacks/events:
+
+```ts
+const session = howone.ai.generateImage.stream(
+  { prompt },
+  {
+    onStreamContent: (delta) => appendLog(delta),
+    onProgress: (progress) => setProgress(progress),
+    onError: (error) => setStatus({ type: 'error', message: error.message }),
+    onComplete: (result) => setResult(result.finalResult),
+  },
+)
+```
+
+## Auth Adapter Contract
+
+Use `AuthAdapter` for custom/headless auth. It is the only supported extension point for token
+ownership outside the SDK defaults.
+
+```ts
+type AuthAdapter = {
+  name?: string
+  getToken?: () => string | null | Promise<string | null>
+  setToken?: (token: string | null) => void | Promise<void>
+  getUser?: (token: string | null) => AuthUser | null | Promise<AuthUser | null>
+  login?: (options?: { returnUrl?: string }) => void | Promise<void>
+  logout?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
+  clearSession?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
+  subscribe?: (listener: (state: AuthState) => void) => (() => void) | void
+}
+```
+
+Rules:
+
+- Default hosted auth must work without an adapter.
+- External providers must use `mode: 'headless'` plus `adapter`.
+- Custom in-app HowOne login should usually use `mode: 'custom'`, `loginPath`, and SDK OTP/OAuth helpers.
+- `client.me()` and `client.requireMe()` are the canonical user APIs.
+- `client.auth.isAuthenticated()` is a quick token check, not a first-load user fetch.
+
+## AI Agent Design Rules
+
+Generated app code should have one stable SDK singleton:
+
+```ts
+import howone from '@/lib/sdk'
+```
+
+Agents should prefer:
+
+1. `howone.entities.*` for private/authenticated data;
+2. `howone.public.entities.*` for public access;
+3. `pickEntityPayload()` / `assertEntityPayload()` when mapping broad UI or AI objects to entity writes;
+4. `assertPublicEntityQuery()` when generated code has access to the synced definition;
+5. `howone.ai.*` for workflow execution;
+6. `runAiActionAndPersist()` when the product needs durable AI history;
+7. `howone.upload.*` for files;
+8. `howone.schema.*` for schema tools;
+9. `howone.raw` only as escape hatch.
+
+Agents must not:
+
+- hardcode HowOne URLs;
+- manually build workflow SSE URLs;
+- call workflows by display name instead of UUID;
+- persist UI-only or workflow-extra fields;
+- add frontend UI APIs to the SDK;
+- remove the default HowOne floating logo unless explicitly asked.
+
+## Adding New SDK Capabilities
+
+When adding a new capability, choose one of these shapes:
+
+```ts
+client.capability.method(input, options)
+client.capability.stream(input, callbacks)
+client.capability.configure(adapter)
+```
+
+Prefer these names:
+
+- `run` for one-shot AI/workflow execution;
+- `stream` for session-based execution with callbacks;
+- `events` for async iterables;
+- `query/list/get/create/update/delete` for entities;
+- `configure` only for adapters, not app UI.
+
+Keep returned values serializable and obvious. AI agents should be able to inspect the method name
+and infer the contract.
+
+## Compatibility Rule
+
+Do not break existing generated apps lightly. Prefer:
+
+- add new adapter/callback options;
+- keep old string shorthand (`auth: 'custom'`) working;
+- mark old UI props as deprecated/no-op only when needed;
+- update this skill and the relevant numbered reference in the same change.

package/templates/vite/.howone/skills/howone/04-ai/01-ai-capability-architecture.md

@@ -0,0 +1,205 @@
+# AI Capability Architecture
+
+Use this reference when a HowOne app needs AI generation, editing, analysis, research, media
+creation, file generation, or any workflow-backed behavior.
+
+This file answers: **what AI layer should be designed, in what order, and where each responsibility
+belongs?** For schema details read `02-workflow-contract-rules.md`. For workflow service calls read
+`05-workflow-operations.md`.
+
+## Platform Mental Model
+
+HowOne AI has five distinct layers:
+
+| Layer | Owns | Does not own |
+|---|---|---|
+| Product feature | User-facing goal, UX states, persistence decision | workflow internals |
+| AI capability contract | `name`, `description`, `inputSchema`, `outputSchema`, `outputEntityName`, versions, manifest | database CRUD, UI, auth |
+| External workflow implementation | generated/edited workflow graph behind a `workflowId` | app schema, frontend state |
+| Status/background layer | `request_id` polling, completed/failed state, `workflowConfigID` capture | SDK binding source |
+| SDK binding/app code | `defineAiAction`, Zod schemas, `howone.ai.*`, persistence through entities | workflow generation |
+
+Do not collapse these layers. The common mistakes are:
+
+- putting database writes into the workflow;
+- generating `src/lib/sdk.ts` before `.howone/ai/manifest.json` is synced;
+- using action names instead of workflow UUIDs;
+- treating workflow `outputSchema` as a database schema;
+- faking unsupported AI with static frontend data.
+
+## Source Of Truth
+
+```text
+user request                         = intent
+agent AI contract proposal           = draft
+applied AI capability version        = validated contract
+.howone/ai/manifest.json             = local synced source for SDK codegen
+workflow service completed status    = source for workflowConfigID
+src/lib/sdk.ts                       = generated app binding
+frontend UI                          = SDK consumer
+entity schema                        = persistence contract, separate from AI contract
+```
+
+Never generate SDK bindings from the user prompt or from an unsynced draft.
+
+## Standard AI Feature Flow
+
+Use this flow for new AI features:
+
+1. Classify the feature using `04-ai/04-service-capability-catalog.md`.
+2. Decide whether the feature is supported. If not supported, stop and explain the missing capability.
+3. Decide one workflow per user-facing feature. Use two workflows only for RAG.
+4. Design `inputSchema` and `outputSchema` using `02-workflow-contract-rules.md`.
+5. Preview/apply the AI capability patch through the capability tool.
+6. Sync `.howone/ai/manifest.json`.
+7. Submit workflow create through `external-ai-capability` / workflow operate from the synced manifest.
+8. Store returned `request_id` values for polling.
+9. Poll status until `completed` or `failed`.
+10. On completed + `payload.success === true`, store `payload.workflow_details.new_workflow_config_id`.
+11. Generate/update `src/lib/sdk.ts` using `03-ai-sdk-handoff.md` and `01-architect/02-manifest-codegen.md`.
+12. Implement UI calls through `howone.ai.<action>.run()`, `.stream()`, or `.events()`.
+13. If output must persist, design entity schema and use `runAiActionAndPersist()` when appropriate.
+
+Do not submit external workflow create/update from a hand-written schema. It should come from the
+synced manifest.
+
+## New Feature vs Existing Feature
+
+| Situation | Correct path |
+|---|---|
+| New AI feature, no manifest entry | create AI capability, sync manifest, submit workflow create |
+| Manifest entry exists but no workflow created yet | submit workflow create from manifest |
+| User asks to change input/output contract | update capability contract first, sync, then submit workflow update |
+| User asks to improve behavior only | submit workflow update with `workflowConfigID` and `updatePrompt` |
+| User asks to save outputs/history | design/update database entity after AI output contract is known |
+| User asks for public share of AI result | private history entity + public scoped share entity |
+
+## Create vs Update
+
+Create external workflow when:
+
+- capability has a `workflowId`;
+- no confirmed external implementation exists;
+- no `workflowConfigID` has been captured.
+
+Update external workflow when:
+
+- an external implementation exists;
+- the status layer previously returned `payload.workflow_details.new_workflow_config_id`;
+- you have a concrete `updatePrompt`.
+
+`workflowConfigID` is not the same as `workflowId`.
+
+```text
+workflowId        = stable workflow UUID from manifest, used by SDK execution
+workflowConfigID  = implementation config ID from completed workflow generation/edit status
+request_id        = async operation ID returned by workflow operate endpoint
+```
+
+Do not invent any of these IDs.
+
+## Workflow Count Rule
+
+Default: one user-facing AI feature equals one workflow.
+
+Examples:
+
+| Feature | Workflow count | Why |
+|---|---:|---|
+| Generate illustrated story | 1 | story text + images are one product action |
+| Edit uploaded photo | 1 | one input image + edit prompt -> edited image |
+| Research news briefing | 1 | search + synthesis are one action |
+| Generate video from prompt | 1 | media generation is one action |
+| Chat with uploaded documents | 2 | RAG needs indexing + query workflows |
+
+Do not split normal multi-step behavior into separate workflows. The workflow service handles
+internal orchestration.
+
+## Persistence Boundary
+
+AI workflows produce outputs. They do not own product records.
+
+Workflow may do:
+
+- generate, summarize, translate, classify, extract;
+- search/crawl and synthesize;
+- generate/edit/analyze images, video, and audio;
+- retrieve financial or academic data;
+- save/read generated files through URL-based storage.
+
+Workflow must not do:
+
+- database create/read/update/delete;
+- authentication/session logic;
+- file upload from browser raw bytes;
+- payment processing;
+- owner assignment or permissions;
+- app navigation, UI state, toast, or modal logic.
+
+If the product needs durable history, use entity persistence outside the workflow:
+
+```ts
+await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input,
+  createPending: (input) => ({ prompt: input.prompt, status: 'pending' }),
+  run: (input) => howone.ai.generateImage.run(input),
+  mapCompleted: ({ output }) => ({ status: 'completed', resultUrl: output.generated_image_url }),
+})
+```
+
+## Unsupported AI Behavior
+
+If a user explicitly requires behavior not available in the workflow service, stop that AI path.
+
+Do not:
+
+- fake AI with static templates;
+- hide the unsupported part;
+- build a UI that pretends the workflow exists;
+- replace the requested capability with a different one without saying so;
+- assume private APIs, external datasets, or providers that are not listed.
+
+Correct response:
+
+```text
+This exact AI behavior needs <missing capability>. The current workflow service supports <closest
+available capability>. I can build <narrow supported version>, or we need platform support for
+<missing capability> first.
+```
+
+## Capability Naming
+
+Use stable JavaScript-safe IDs:
+
+```text
+generateIllustration
+summarizeDocument
+researchNewsBriefing
+editProductPhoto
+transcribeAudio
+```
+
+Avoid:
+
+- display labels with spaces;
+- names that collide with base methods: `run`, `stream`, `events`;
+- provider names: `openAiImage`, `geminiAnalyze`;
+- implementation names: `searchThenSummarize`.
+
+The description can be human readable. The ID must be stable for codegen.
+
+## AI Architecture Checklist
+
+Before editing files:
+
+- Feature maps to available workflow capabilities.
+- One workflow per feature unless RAG.
+- Description says what the user gets, not how tools run.
+- Input schema accepts URLs for files, not raw bytes.
+- Output schema contains only requested result fields.
+- Input and output property names do not overlap.
+- Text output descriptions specify language behavior.
+- Persistence is modeled as entity schema, not workflow CRUD.
+- `workflowId`, `request_id`, and `workflowConfigID` are not guessed.
+- SDK binding will be generated only after manifest sync.