howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/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-sdk/04-ai/01-ai-capability-architecture.md

@@ -1,142 +1,205 @@
 # AI Capability Architecture
 
-Use this reference when a HowOne app needs AI generation, editing, analysis, research, or other
-workflow-backed behavior.
+Use this reference when a HowOne app needs AI generation, editing, analysis, research, media
+creation, file generation, or any workflow-backed behavior.
 
-## Core Split
+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`.
 
-HowOne AI has four separate layers:
+## Platform Mental Model
 
-1. **Capability contract**: `ai-capability-design` owns the name, description, input schema, output
-   schema, output entity name, workflow ID, versions, preview, apply, restore, and manifest sync.
-2. **External workflow implementation**: `external-ai-capability` submits create/update operations
-   to the workflow service using the synced contract from `.howone/ai/manifest.json`.
-3. **Workflow status/background layer**: status checking, request tracking, completion, failure, and
-   durable background-task behavior are handled outside the contract tool. Preserve request IDs and
-   workflow config IDs for that layer.
-4. **SDK binding and UI**: `src/lib/sdk.ts` is generated from `.howone/ai/manifest.json`, then the
-   app calls `howone.ai.<capability>.run()`, `.stream()`, or `.events()`.
+HowOne AI has five distinct layers:
 
-Do not collapse these layers. The common failure is putting workflow implementation, persistence,
-and UI details into the capability schema.
+| 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 |
 
-## Source of Truth
+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
-agent proposal != source of truth
-applied AI capability version = source of truth
-.howone/ai/manifest.json = local source for codegen
-src/lib/sdk.ts = generated binding output
-external workflow service = implementation builder/editor
+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
 ```
 
-The agent proposes a contract. The backend validates and versions it. The sync tool writes the
-manifest. App code is generated from the manifest.
+Never generate SDK bindings from the user prompt or from an unsynced draft.
 
-## Standard AI Feature Workflow
+## Standard AI Feature Flow
 
-1. Inspect current AI state with `ai-capability-design`.
-2. Design one complete capability patch for the feature.
-3. Preview the patch.
-4. Apply the same operations.
-5. Sync AI artifacts.
-6. Read `.howone/ai/manifest.json`.
-7. Submit external workflow create/update with `external-ai-capability`.
-8. Preserve returned `requestIds` for the status/background-task layer.
-9. Generate or update `src/lib/sdk.ts` from the manifest.
-10. Implement UI calls through `howone.ai.*`.
-11. If generated output must be stored, design database entities after the AI output schema exists.
+Use this flow for new AI features:
 
-Do not preview a patch and then submit different operations. Do not restate schemas in
-`external-ai-capability`; it loads the manifest.
+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.
 
-## Unsupported AI Requests
+Do not submit external workflow create/update from a hand-written schema. It should come from the
+synced manifest.
 
-If the user explicitly asks for AI capability and the feature cannot be implemented with the
-available workflow service capabilities, stop the AI implementation task and report the gap.
+## New Feature vs Existing Feature
 
-Do not:
+| 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 |
 
-- fake the AI feature with static mock data.
-- implement a frontend-only placeholder that pretends AI works.
-- design a workflow that assumes unavailable tools, providers, APIs, or private datasets.
-- silently drop the AI part and continue building a non-AI version.
-- move forbidden work such as database CRUD, auth, upload handling, payments, or app state into the
-  workflow.
+## Create vs Update
 
-The correct response is to state which requested AI behavior is unsupported, which capability is
-missing or which rule blocks it, and what narrower supported alternative could be built.
+Create external workflow when:
 
-Only continue implementation when the remaining feature still satisfies the user's intent after
-the unsupported AI capability is removed or narrowed.
+- capability has a `workflowId`;
+- no confirmed external implementation exists;
+- no `workflowConfigID` has been captured.
 
-## Create vs Update
+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`.
 
-Use `external-ai-capability` with `mode: "create"` when a capability has no external implementation.
-The tool reads `workflowId`, `inputSchema`, `outputSchema`, and `outputEntityName` from the synced
-manifest.
+`workflowConfigID` is not the same as `workflowId`.
 
-Use `mode: "update"` when the external workflow implementation needs to change. Updates require:
+```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.
 
-- `capabilityName`
-- `workflowConfigID`
-- `updatePrompt`
+## Workflow Count Rule
+
+Default: one user-facing AI feature equals one workflow.
+
+Examples:
 
-`workflowConfigID` must come from a confirmed workflow status result, specifically
-`payload.workflow_details.new_workflow_config_id`. Do not invent it, omit it, or substitute
-`workflowId`.
+| 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 |
 
-If the input/output schema changes, update the capability contract first, sync the manifest, then
-submit the external workflow update.
+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 persist app state.
+AI workflows produce outputs. They do not own product records.
 
-Workflow can do:
+Workflow may do:
 
-- text generation, summarization, translation, classification, extraction
-- image, video, and audio generation/editing/analysis
-- web research and page crawling
-- financial or academic retrieval
-- file generation or file reading through URLs
+- 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 or session handling
-- upload handling
-- payment processing
-- app state management
-- owner assignment or record permissions
+- 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 }),
+})
+```
 
-If the app saves AI output, derive entity fields from `outputSchema` and add only necessary request
-metadata such as prompt, selected options, status, timestamps, or references.
+## Unsupported AI Behavior
 
-## Workflow Count
+If a user explicitly requires behavior not available in the workflow service, stop that AI path.
 
-Default rule: one user-facing AI feature maps to one capability and one workflow.
+Do not:
 
-Examples:
+- 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
 
-- Story + illustration generator: one workflow that returns story text and generated image URLs.
-- Image edit feature: one workflow that accepts source image URL and edit instruction, returns
-  edited image URL.
-- News briefing: one workflow that searches and summarizes, returns briefing and source links.
+Use stable JavaScript-safe IDs:
 
-RAG is the exception:
+```text
+generateIllustration
+summarizeDocument
+researchNewsBriefing
+editProductPhoto
+transcribeAudio
+```
 
-- indexing workflow: ingests documents and creates retrieval/indexing artifacts.
-- query workflow: answers questions from the indexed knowledge base.
+Avoid:
 
-Do not split normal sequential AI steps into multiple capabilities unless they are independently
-triggered product features.
+- display labels with spaces;
+- names that collide with base methods: `run`, `stream`, `events`;
+- provider names: `openAiImage`, `geminiAnalyze`;
+- implementation names: `searchThenSummarize`.
 
-## Capability Naming
+The description can be human readable. The ID must be stable for codegen.
 
-Use stable JavaScript-safe identifiers for capability names, for example `generateIllustration` or
-`summarizeDocument`. Do not use display labels as identifiers.
+## AI Architecture Checklist
 
-Avoid names that collide with action methods: `run`, `stream`, `events`.
+Before editing files:
 
-Use `outputEntityName` only when the generated output has a natural persisted record shape.
+- 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.