howone 0.1.23 → 0.1.26

package/templates/vite/.howone/skills/howone-sdk/03-sdk/04-react-integration.md

@@ -1,398 +0,0 @@
-# React Integration
-
-## What `@howone/sdk/react` Provides
-
-`@howone/sdk/react` is a **thin UI layer** for auth state, theme, and loading spinners. It does **not** provide entity, query, or AI data hooks.
-
-Exports:
-- `HowOneProvider` — all-in-one app provider (auth, theme, toasts, floating button)
-- `useHowoneContext` — access auth state (user, token, isAuthenticated, logout)
-- `FloatingButton` — a floating action button (shows Login when unauthenticated)
-- `Loading` — full-page or inline loading component
-- `LoadingSpinner` — headless spinner for composition
-
----
-
-## Import
-
-```ts
-import {
-  HowOneProvider,
-  useHowoneContext,
-  FloatingButton,
-  Loading,
-  LoadingSpinner,
-} from '@howone/sdk/react'
-```
-
----
-
-## HowOneProvider
-
-Wrap your entire app. Provides auth, theme, and toast context to all children.
-
-`HowOneProvider` reads SDK environment and project defaults from `createClient`. Configure
-`projectId` and `env` once in `src/lib/sdk.ts`; do not pass a separate env to the provider.
-
-```tsx
-// main.tsx or app/layout.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { HowOneProvider } from '@howone/sdk/react'
-import './lib/sdk'
-import App from './App'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <HowOneProvider
-      auth="required"
-      brand="visible"
-      theme="system"
-    >
-      <App />
-    </HowOneProvider>
-  </React.StrictMode>
-)
-```
-
-### HowOneProviderProps
-
-```ts
-type HowOneAuthMode = 'required' | 'optional' | 'none'
-type HowOneThemeMode = 'dark' | 'light' | 'system' | 'inherit'
-type HowOneBrandMode = 'visible' | 'hidden'
-
-interface HowOneProviderProps {
-  children: React.ReactNode
-
-  // Optional override. Prefer configuring projectId once in createClient.
-  projectId?: string
-
-  // Auth behaviour
-  auth?: HowOneAuthMode
-  // 'required' — redirects unauthenticated users to login page
-  // 'optional' — allows both authenticated and unauthenticated users
-  // 'none'     — disables auth entirely
-
-  // Brand button (HowOne branding)
-  brand?: HowOneBrandMode          // default: 'visible'
-  showBrandButton?: boolean        // alias for brand
-
-  // Theme
-  theme?: HowOneThemeMode          // default: 'system'
-  themeStorageKey?: string         // localStorage key for theme preference
-  forceTheme?: boolean             // ignore user preference and force theme
-}
-```
-
-### Common provider configurations
-
-```tsx
-// Public app — no auth required
-<HowOneProvider auth="none" theme="system" brand="hidden">
-  <App />
-</HowOneProvider>
-
-// Auth-gated app — redirect to login if not authenticated
-<HowOneProvider auth="required" theme="system">
-  <App />
-</HowOneProvider>
-
-// Optional auth — user can browse without logging in
-<HowOneProvider auth="optional" theme="inherit" brand="visible">
-  <App />
-</HowOneProvider>
-
-// Dark mode forced
-<HowOneProvider auth="required" theme="dark" forceTheme>
-  <App />
-</HowOneProvider>
-```
-
----
-
-## useHowoneContext
-
-Access auth state inside any component wrapped by `HowOneProvider`.
-
-```ts
-type HowoneContextValue = {
-  user: {
-    id: string       // backend owner id; same as userId when JWT has userId
-    userId?: string  // authenticated backend user id when present in JWT
-    puid?: string    // public UUID; do not use as public ownerId scope
-    email: string
-    name: string
-    avatar: string
-    appId?: string
-  } | null
-  token: string | null
-  isAuthenticated: boolean
-  logout: () => void
-}
-```
-
-### Usage
-
-```tsx
-import { useHowoneContext } from '@howone/sdk/react'
-
-function UserMenu() {
-  const { user, isAuthenticated, logout } = useHowoneContext()
-
-  if (!isAuthenticated || !user) {
-    return <a href="/login">Login</a>
-  }
-
-  return (
-    <div>
-      <img src={user.avatar} alt={user.name} />
-      <span>{user.name}</span>
-      <button onClick={logout}>Logout</button>
-    </div>
-  )
-}
-```
-
-### Conditional rendering based on auth state
-
-```tsx
-function Dashboard() {
-  const { isAuthenticated, user } = useHowoneContext()
-
-  if (!isAuthenticated) {
-    return <div>Please log in to continue.</div>
-  }
-
-  return <div>Welcome, {user?.name}!</div>
-}
-```
-
-### Using token for direct API calls
-
-```tsx
-import { useHowoneContext } from '@howone/sdk/react'
-
-function DebugPanel() {
-  const { token } = useHowoneContext()
-
-  async function copyToken() {
-    if (token) await navigator.clipboard.writeText(token)
-  }
-
-  return (
-    <button onClick={copyToken} disabled={!token}>
-      Copy JWT Token
-    </button>
-  )
-}
-```
-
----
-
-## FloatingButton
-
-A floating action button that renders in the bottom corner of the screen. When unauthenticated, it shows a "Login" label by default.
-
-```tsx
-import { FloatingButton } from '@howone/sdk/react'
-
-// Default — shows Login/brand button
-<FloatingButton />
-
-// Custom text and handler
-<FloatingButton
-  text="Get Started"
-  onClick={() => router.push('/signup')}
-/>
-
-// Custom styling
-<FloatingButton
-  text="Support"
-  onClick={() => setShowChat(true)}
-  className="bg-blue-600 hover:bg-blue-700"
-/>
-```
-
-### FloatingButtonProps
-
-```ts
-interface FloatingButtonProps {
-  text?: string       // button label (default: 'Login' or brand text)
-  onClick?: () => void
-  className?: string  // additional CSS classes
-}
-```
-
----
-
-## Loading Components
-
-### Loading — full-page or inline loading state
-
-```tsx
-import { Loading } from '@howone/sdk/react'
-
-// Full-screen overlay
-<Loading fullScreen label="Loading your workspace..." />
-
-// Inline with description
-<Loading
-  label="Generating story..."
-  description="This may take a moment"
-  size="lg"
-  tone="brand"
-/>
-
-// Minimal
-<Loading />
-```
-
-### LoadingSpinner — headless spinner
-
-```tsx
-import { LoadingSpinner } from '@howone/sdk/react'
-
-// Sizes: 'sm' | 'md' | 'lg'
-// Tones: 'brand' | 'neutral' | 'inverse'
-
-<LoadingSpinner size="md" tone="brand" />
-<LoadingSpinner size="sm" tone="neutral" className="mr-2" />
-```
-
-### LoadingProps
-
-```ts
-type LoadingSize = 'sm' | 'md' | 'lg'
-type LoadingTone = 'brand' | 'neutral' | 'inverse'
-
-interface LoadingProps {
-  size?: LoadingSize        // default: 'md'
-  tone?: LoadingTone        // default: 'brand'
-  label?: string            // primary text
-  description?: string      // secondary text
-  className?: string
-  fullScreen?: boolean      // renders over full viewport
-}
-
-interface LoadingSpinnerProps {
-  size?: LoadingSize
-  tone?: LoadingTone
-  className?: string
-}
-```
-
----
-
-## Entity and AI Data in React
-
-`@howone/sdk/react` provides **no data hooks**. Use `useEffect`/`useState` or TanStack Query around the plain async SDK calls.
-
-### Pattern: auth-gated data fetch
-
-```tsx
-import { useEffect, useState } from 'react'
-import { useHowoneContext } from '@howone/sdk/react'
-import { Loading } from '@howone/sdk/react'
-import howone, { type StoryRecord } from '@/lib/sdk'
-
-function MyStories() {
-  const { isAuthenticated } = useHowoneContext()
-  const [stories, setStories] = useState<StoryRecord[]>([])
-  const [loading, setLoading] = useState(false)
-
-  useEffect(() => {
-    if (!isAuthenticated) return
-
-    setLoading(true)
-    howone.entities.Story.query.mine({ page: { number: 1, size: 20 } })
-      .then(result => setStories(result.items))
-      .finally(() => setLoading(false))
-  }, [isAuthenticated])
-
-  if (!isAuthenticated) return <div>Please log in.</div>
-  if (loading) return <Loading label="Loading your stories..." />
-
-  return (
-    <ul>
-      {stories.map(s => <li key={s.id}>{s.title}</li>)}
-    </ul>
-  )
-}
-```
-
-### Pattern: Full app layout
-
-```tsx
-// src/main.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { HowOneProvider } from '@howone/sdk/react'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import './lib/sdk'
-import App from './App'
-
-const queryClient = new QueryClient()
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <HowOneProvider
-      auth="required"
-      theme="system"
-      brand="visible"
-    >
-      <QueryClientProvider client={queryClient}>
-        <App />
-      </QueryClientProvider>
-    </HowOneProvider>
-  </React.StrictMode>
-)
-```
-
-### Pattern: conditional AI action based on auth
-
-```tsx
-import { useState } from 'react'
-import { useHowoneContext } from '@howone/sdk/react'
-import howone from '@/lib/sdk'
-
-function AIGenerateButton({ topic }: { topic: string }) {
-  const { isAuthenticated } = useHowoneContext()
-  const [loading, setLoading] = useState(false)
-  const [result, setResult] = useState<string | null>(null)
-
-  async function handleGenerate() {
-    if (!isAuthenticated) {
-      howone.auth.login()
-      return
-    }
-    setLoading(true)
-    try {
-      const output = await howone.ai.generateStory.run({ topic, language: 'en' })
-      setResult(output.content)
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  return (
-    <div>
-      <button onClick={handleGenerate} disabled={loading}>
-        {loading ? 'Generating...' : isAuthenticated ? 'Generate' : 'Login to Generate'}
-      </button>
-      {result && <p>{result}</p>}
-    </div>
-  )
-}
-```
-
----
-
-## Common Mistakes
-
-| Mistake | Correct Pattern |
-|---|---|
-| `import { useHowoneContext } from '@howone/sdk'` | Import from `'@howone/sdk/react'` |
-| Expecting entity data hooks from `useHowoneContext` | Use `useEffect`/`useState` + `howone.entities.*` directly |
-| Placing `<HowOneProvider>` inside a component that re-renders | Place at root level (main.tsx / app layout) |
-| Using `user.id` without null-checking `user` | Guard: `if (!user) return` or use optional chaining `user?.id` |

package/templates/vite/.howone/skills/howone-sdk/04-ai/.gitkeep

@@ -1 +0,0 @@
-

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

@@ -1,142 +0,0 @@
-# AI Capability Architecture
-
-Use this reference when a HowOne app needs AI generation, editing, analysis, research, or other
-workflow-backed behavior.
-
-## Core Split
-
-HowOne AI has four separate layers:
-
-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()`.
-
-Do not collapse these layers. The common failure is putting workflow implementation, persistence,
-and UI details into the capability schema.
-
-## 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
-```
-
-The agent proposes a contract. The backend validates and versions it. The sync tool writes the
-manifest. App code is generated from the manifest.
-
-## Standard AI Feature Workflow
-
-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.
-
-Do not preview a patch and then submit different operations. Do not restate schemas in
-`external-ai-capability`; it loads the manifest.
-
-## Unsupported AI Requests
-
-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.
-
-Do not:
-
-- 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.
-
-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.
-
-Only continue implementation when the remaining feature still satisfies the user's intent after
-the unsupported AI capability is removed or narrowed.
-
-## Create vs Update
-
-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.
-
-Use `mode: "update"` when the external workflow implementation needs to change. Updates require:
-
-- `capabilityName`
-- `workflowConfigID`
-- `updatePrompt`
-
-`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`.
-
-If the input/output schema changes, update the capability contract first, sync the manifest, then
-submit the external workflow update.
-
-## Persistence Boundary
-
-AI workflows produce outputs. They do not persist app state.
-
-Workflow can 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
-
-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
-
-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.
-
-## Workflow Count
-
-Default rule: one user-facing AI feature maps to one capability and one workflow.
-
-Examples:
-
-- 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.
-
-RAG is the exception:
-
-- indexing workflow: ingests documents and creates retrieval/indexing artifacts.
-- query workflow: answers questions from the indexed knowledge base.
-
-Do not split normal sequential AI steps into multiple capabilities unless they are independently
-triggered product features.
-
-## Capability Naming
-
-Use stable JavaScript-safe identifiers for capability names, for example `generateIllustration` or
-`summarizeDocument`. Do not use display labels as identifiers.
-
-Avoid names that collide with action methods: `run`, `stream`, `events`.
-
-Use `outputEntityName` only when the generated output has a natural persisted record shape.

package/templates/vite/.howone/skills/howone-sdk/04-ai/02-workflow-contract-rules.md

@@ -1,169 +0,0 @@
-# Workflow Contract Rules
-
-Use this reference when designing `inputSchema`, `outputSchema`, and capability descriptions for
-HowOne AI workflows.
-
-## Loose JSON Schema
-
-Workflow schemas should be loose enough for an AI workflow engine.
-
-Rules:
-
-- Require only essential inputs.
-- Mark non-essential options optional.
-- Prefer `string` with a clear description over restrictive enums when user values are open-ended.
-- Avoid `minLength`, `maxLength`, `pattern`, and narrow validation unless there is a concrete
-  technical reason.
-- Avoid nested objects when a simple described string is enough.
-- Avoid exposing implementation knobs the user does not need.
-
-Good:
-
-```json
-{
-  "tone": {
-    "type": "string",
-    "description": "Desired writing tone, e.g. formal, casual, humorous, empathetic, professional."
-  }
-}
-```
-
-Use enums only for truly closed domains.
-
-## URLs, Not Raw Files
-
-All file exchange uses URLs.
-
-Rules:
-
-- File inputs are strings with `format: "uri"`, such as `document_url`, `source_image_url`, or
-  `audio_file_url`.
-- File outputs are strings with `format: "uri"`, such as `generated_image_url`, `edited_video_url`,
-  or `result_pdf_url`.
-- Never use base64, raw bytes, inline file content, or `contentEncoding`.
-- The app uploads user files first, then passes the URL to the workflow.
-
-## Output Minimalism
-
-The workflow will try to fill every output field. Only ask for fields the product needs.
-
-Usually forbidden unless explicitly requested:
-
-- timestamps and processing time
-- file size, MIME type, encoding, dimensions, frame rate, bitrate
-- confidence scores and bounding boxes
-- model, provider, version, cost, or internal execution metadata
-- style/tone metadata when the user only asked for an asset
-
-Examples:
-
-| User Need | Good Output | Avoid |
-|---|---|---|
-| Summarize a document | `summary` | `summary`, `word_count`, `reading_time` |
-| Generate an image | `generated_image_url` | `generated_image_url`, `model_used`, `color_palette` |
-| OCR an image | `extracted_text` | `extracted_text`, `confidence_score`, `bounding_boxes` |
-
-## No Input/Output Name Overlap
-
-Input and output property names must not overlap. The workflow engine uses a shared parameter
-namespace.
-
-Bad:
-
-```json
-{
-  "inputSchema": { "properties": { "text": { "type": "string" } } },
-  "outputSchema": { "properties": { "text": { "type": "string" } } }
-}
-```
-
-Good:
-
-```json
-{
-  "inputSchema": { "properties": { "source_text": { "type": "string" } } },
-  "outputSchema": { "properties": { "translated_text": { "type": "string" } } }
-}
-```
-
-Common pairs:
-
-- `source_text` -> `translated_text`
-- `source_content` -> `summary`
-- `source_image_url` -> `edited_image_url`
-- `description_prompt` -> `generated_image_url`
-
-## Output Language
-
-Every text output field description must specify the language rule.
-
-Use one of these patterns:
-
-- fixed: "Summary in English."
-- input-driven: "Translated text in the target language specified by `target_language`."
-- source-driven: "Summary in the same language as the source document."
-- mixed: "Extracted text, which may contain mixed Chinese and English content."
-
-Do not write vague descriptions like "The translated text."
-
-## Description Says What, Not How
-
-`capability.description` describes the user outcome.
-
-Do:
-
-```json
-{
-  "description": "Searches the web for the latest news on a topic and produces a structured briefing with source links."
-}
-```
-
-Do not:
-
-```json
-{
-  "description": "First calls search_web, then summarizes each article with an LLM, then saves JSON."
-}
-```
-
-Never mention internal tool names, step sequences, providers, or model names in the capability
-description.
-
-## Available Capability Families
-
-Design only around capabilities available to the workflow service:
-
-- web search and page crawling
-- image generation, editing, analysis, OCR
-- video generation, editing, concatenation, frame extraction
-- audio generation, recognition, merging
-- financial price history retrieval
-- academic paper search and bibliography
-- file storage/read for JSON, YAML, CSV, PDF, Markdown, TXT
-- email sending
-- RSS feed fetching
-- Airbnb search
-- Hacker News search
-
-If the requested product needs unavailable functionality, redesign the feature around available
-capabilities or exclude it explicitly.
-
-When the user explicitly requires the unavailable AI behavior, terminate the AI task instead of
-building a fake or silently degraded implementation. Report the unsupported requirement and the
-closest supported alternative.
-
-## External Data Assumptions
-
-Do not assume the user can provide external datasets unless they explicitly say so.
-
-For "stock analysis", use a workflow input such as `trading_symbol` and let the workflow retrieve
-history. Do not require `stock_data_csv_url` unless the user says they have a CSV.
-
-For "latest news", use web search inside the workflow. Do not ask the user to provide article URLs
-unless that is the product requirement.
-
-## MVP Limit
-
-Keep AI app generation to at most five core features. Exclude feedback forms, onboarding tutorials,
-notification settings, export, sharing, personalization, and preferences unless the user explicitly
-requests them.