howone 0.1.30 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md

@@ -1,215 +1,171 @@
 # App Generation Architect
 
-Use this file before building or changing a HowOne generated app. It decides which platform tracks
-must be used and what order to execute them in.
+Read immediately after `skill(name="howone")` and before platform design tools, SDK contract
+edits, or implementation guesses.
 
-This is the planning layer. It should prevent the agent from jumping straight into UI code while
-missing schema, auth, AI, manifest, or SDK binding contracts.
+HowOne is a generated app platform. This file classifies **user scope**, separates **platform
+contracts** from **app-owned integrations**, routes to tracks (see `SKILL.md` index), and sets
+data/auth posture. File-level detail stays in each track—not here.
 
-## Platform Shape
+## Scope classification
 
-HowOne generated apps have four product layers:
+Map the user request to surfaces. Include only what they need.
 
-| Layer | Source of truth | App code should do |
+| Need | Tracks | Notes |
 |---|---|---|
-| Backend database | synced `.howone/database/manifest.json` | generate entity types/bindings and call SDK |
-| AI capabilities | synced `.howone/ai/manifest.json` + workflow status | generate AI action bindings and call SDK |
-| SDK runtime | `@howone/sdk` + `src/lib/sdk.ts` | centralize env/auth/entities/AI/upload |
-| Frontend app | user experience | own UI, state, feedback, forms, navigation |
+| Unclear or full product scope | `01-architect/` (+ others as discovered) | Finish this file before other tracks |
+| Persisted app data on HowOne | `02-entity-schema/` → sync → `04-app-sdk/` | Skip if no storage |
+| HowOne AI features | `03-ai-capabilities/` → sync → `04-app-sdk/` | Verify catalog before design |
+| SDK wiring, auth, UI calls | `04-app-sdk/` | After manifests exist when contracts apply |
+| UI only, no HowOne data/AI | App code under `{appRoot}` | No schema/AI design tools |
+| External systems the user provides | App code + config | Not platform contracts unless combined with rows above |
 
-The agent may propose schema/capability changes, but the validated/synced manifests drive code.
+**Mixed scope:** read at least one file per touched track (`SKILL.md` index) before writing.
 
-```text
-user request -> architecture decision -> backend/AI contracts -> sync manifests -> sdk binding -> UI
-```
-
-Do not skip the binding layer. UI code should import `howone` from `src/lib/sdk.ts`, not construct
-raw URLs or guessed entity/action names.
+## HowOne platform boundary
 
-## First Decision: What Surfaces Are Touched?
+Use this decision model for **any** user request. Do not maintain a mental deny-list of technologies
+(K8s, message buses, custom protocols, etc.). Ask whether the ask is a **platform contract surface**
+or **app-owned**.
 
-Classify the request before editing.
+### Platform provides (evidence required)
 
-| User request says | Touched surfaces | Required references |
+| Surface | Evidence to check | Design track |
 |---|---|---|
-| "store/save/history/list/my data" | database + SDK + UI | `02-database/`, `03-sdk/02-entity-operations.md` |
-| "login/account/my/private" | auth + database access | `03-sdk/03-auth.md`, `03-sdk/04-react-integration.md` |
-| "public page/share/link/landing/catalog" | public access + SDK public namespace | `02-database/03-data-access-patterns.md` |
-| "AI/generate/analyze/summarize/research/edit image/video/audio" | AI contract + workflow + SDK | `04-ai/` |
-| "upload file/image/audio/pdf" | upload + maybe AI URL input | `03-sdk/05-file-upload.md`, `04-ai/02-workflow-contract-rules.md` |
-| "change schema/add field/new table" | schema operations + manifest codegen | `02-database/02-schema-operations.md`, `01-architect/02-manifest-codegen.md` |
-| "frontend only" | SDK usage + UI | `03-sdk/01-client-setup.md` and relevant SDK docs |
-
-If multiple surfaces are touched, read one reference from each surface before editing.
-
-## Data Posture Decision
-
-Choose data posture before schema and UI.
-
-| Product need | Access contract | SDK read |
-|---|---|---|
-| per-user private data | authenticated own, public none | `howone.entities.X.query.mine()` |
-| logged-in shared admin/team data | authenticated all, public none | `howone.entities.X.query()` |
-| anonymous public catalog/feed | authenticated all, public list | `howone.public.entities.X.query()` |
-| one public share/detail page | authenticated own/all, public scoped | `howone.public.entities.X.queryScoped()` |
-| anonymous form submission | authenticated all, public create scoped/any | `howone.public.entities.X.create()` |
-| AI generation history | authenticated own, public none | `runAiActionAndPersist()` + `query.mine()` |
-| AI public share | private history + public scoped share entity | two entities |
-
-Defaults:
-
-- "my" / "per user" / "private" -> authenticated own.
-- "landing page" / "blog" / "gallery" -> public list only if fields are safe.
-- "share link" / "QR" / "public result" -> public scoped, small `maxLimit`.
-- "AI history" -> private history entity; do not make it public just for sharing.
-
-## Auth Decision
-
-| Need | SDK config | Provider behavior |
-|---|---|---|
-| default HowOne login | `createClient({ projectId, env })` | hosted login |
-| custom designed login page using HowOne auth APIs | `auth: 'custom'`, `HowOneProvider auth="none"` | app owns login UI |
-| external identity provider/JWT | `auth: { mode: 'headless', adapter }` | adapter owns token/user |
-| public-only app | `auth: 'none'` | no auth guard |
-
-Rules:
-
-- Keep the bottom-right HowOne `FloatingButton` by default unless explicitly hidden.
-- SDK must not add toast/overlay/login-page UI.
-- Use `client.me()` or `client.requireMe()` for first-load user resolution.
-- Do not use `auth.isAuthenticated()` as the only initial truth when user data must be loaded.
-
-## Backend Feature Workflow
-
-Use when persistence or schema changes are needed:
+| Persisted structured data on HowOne | Schema tools + `{appRoot}/.howone/database/manifest.json` | `02-entity-schema/` |
+| AI execution on HowOne workflow service | `03-service-capability-catalog.md` + AI manifest + AI tools | `03-ai-capabilities/` |
+| App calls HowOne runtime | Synced manifests + `04-app-sdk/` reference for that behavior | `04-app-sdk/` |
+| Mutating platform contracts | `backend-api-design`, `ai-capability-design`, sync tools, `external-ai-capability` | Per surface |
 
-1. Read `02-database/01-schema-design.md`.
-2. Read `02-database/02-schema-operations.md`.
-3. Inspect current schema state/manifest.
-4. Design complete entity contract: fields, required, access, indexes, presentation.
-5. Preview one complete schema patch.
-6. Apply the exact previewed patch if risk is acceptable.
-7. Sync schema artifacts from returned version.
-8. Read `.howone/database/manifest.json`.
-9. Update `src/lib/sdk.ts` from manifest using `01-architect/02-manifest-codegen.md`.
-10. Implement UI with `howone.entities.*` or `howone.public.entities.*`.
-11. Validate build/tests.
+If none of these surfaces can express the user's **platform** requirement after checking contracts,
+catalog, and tool schemas, it is a **platform gap**—not an automatic ban on whatever technology the
+user named.
 
-Risk stops:
+### App-owned (not platform gap)
 
-- deleting entity/field;
-- making required field without default;
-- broadening public access;
-- enabling public write;
-- changing owner/public scope semantics.
+Anything the user runs, hosts, or buys **outside** HowOne contracts: orchestration, clusters,
+custom APIs, message systems, identity products, analytics, payment gateways, etc.
 
-## AI Feature Workflow
+- Implement in application code and configuration under `{appRoot}`.
+- **Do not refuse** because HowOne does not provision it.
+- **Do not** call platform design tools to fake it as entities, AI capabilities, or manifest fields.
+- **Do not** tell the user they cannot use their own stack—only clarify it is outside HowOne platform scope.
 
-Use when AI capability/workflow is needed:
-
-1. Read `04-ai/01-ai-capability-architecture.md`.
-2. Read `04-ai/04-service-capability-catalog.md` to verify support.
-3. Pick a playbook from `04-ai/06-ai-feature-playbooks.md` when applicable.
-4. Design schemas with `04-ai/02-workflow-contract-rules.md`.
-5. Preview/apply AI capability patch.
-6. Sync `.howone/ai/manifest.json`.
-7. Submit external workflow create/update using `04-ai/05-workflow-operations.md`.
-8. Preserve returned `request_id`.
-9. Poll status until terminal; preserve `workflowConfigID` on success.
-10. Update `src/lib/sdk.ts` with `04-ai/03-ai-sdk-handoff.md`.
-11. Implement UI through `howone.ai.*`.
-12. If output persists, use `02-database/05-ai-persistence-patterns.md`.
-
-Do not build fake AI. If the required capability is unsupported, report the exact gap.
-
-## Manifest Codegen Workflow
-
-Run after database or AI sync:
-
-1. Read current `src/lib/sdk.ts`.
-2. Read synced manifests.
-3. Preserve existing exports and naming style.
-4. Generate/update:
-   - entity `Record/Create/Update` types;
-   - optional exported `*EntityDefinition` for guards;
-   - `client.entity<...>()` bindings;
-   - AI Zod schemas and `defineAiAction(...)`;
-   - composed `howone` export.
-5. Never write generated source under `.howone/`.
-
-## Common User Situations
-
-### User asks for "just a frontend"
-
-Still check whether UI needs stored data, auth, upload, or AI. If it only renders static/local state,
-do not invent schema or workflow. If it saves anything, use database flow.
-
-### User asks for "AI app" but no persistence
-
-Design AI capability and SDK binding only. Keep results in app state. Do not create entities unless
-history, refresh resilience, user library, or share page is needed.
-
-### User asks for "AI app with history"
-
-Design AI first, then database:
+### Boundary decision (always)
 
 ```text
-AI output contract -> Generation entity -> runAiActionAndPersist -> history query.mine()
+1. What did the user ask for?
+2. Does it require HowOne persisted data? → entity-schema path or skip
+3. Does it require HowOne AI? → catalog + ai-capabilities path or skip
+4. Is it only their external infrastructure? → app-owned; wire in UI/config
+5. Did they ask for a platform feature with no contract evidence? → platform stop (generic)
+6. Mixed? → platform parts via tracks; app-owned parts in app code
 ```
 
-Do not put history fields into workflow output unless the AI itself must generate them.
+### Platform scope rules
 
-### User asks for "public AI result"
+- **No invented platform APIs:** Only fields and behaviors present in manifests, catalog, tools, or documented SDK references.
+- **No invalid shortcuts:** Do not handwrite `.howone/` metadata or guess version/workflow identifiers.
+- **Stop wording:** Name the **missing contract surface** (e.g. no catalog family, no manifest binding, no tool operation)—not the user's technology choice.
 
-Use two entities:
+When stopping a platform path, separate what HowOne can provide from what remains possible via app-owned integration.
 
-- private `Generation` for owner history and retry;
-- public scoped `SharedGeneration` for anonymous viewing.
+Inspect-only platform reads do not replace this file before the first **design write**.
 
-Do not expose private prompt/history broadly.
+## Platform layers
 
-### User asks for "latest/current/research"
+| Layer | Source of truth | App responsibility |
+|---|---|---|
+| Database | `{appRoot}/.howone/database/manifest.json` | Types/bindings via SDK |
+| AI | `{appRoot}/.howone/ai/manifest.json` + workflow status | AI bindings via SDK |
+| SDK | `@howone/sdk` + `{appRoot}/src/lib/sdk.ts` | Single entry for HowOne calls |
+| Frontend | App code | UI, state, feedback |
 
-Use AI workflow with web search/crawling capability. If app also lists saved briefings, add entity
-persistence after output contract.
+Validated/synced manifests drive code—not prompts or memory.
 
-### User asks to modify existing AI behavior
+```text
+user request → scope → platform contracts → sync → sdk binding → UI
+```
 
-If only behavior changes, use external workflow update with `workflowConfigID`.
-If input/output changes, update AI capability contract first, sync manifest, then update workflow
-and SDK bindings.
+Import `howone` from `src/lib/sdk.ts`; do not guess entity/action names or platform URLs.
 
-### User asks to change schema used by UI
+## Minimum track reads (after this file)
 
-Change backend schema first, sync, regenerate SDK, then update UI. Do not patch UI types from memory.
+Use `SKILL.md` for the full file index. Typical minimums:
 
-### User asks for custom auth
+| Surface in scope | Read at least |
+|---|---|
+| Entity/schema design | `02-entity-schema/01-schema-design.md`, `02-schema-operations.md` |
+| Queries / public data | add `03-data-access-patterns.md`, `04-query-dsl-and-responses.md` |
+| AI design | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-service-capability-catalog.md`, `02-workflow-contract-rules.md` |
+| AI + saved outputs | add `02-entity-schema/05-ai-persistence-patterns.md` after AI contract is known |
+| Bindings after sync | `02-manifest-codegen.md` + relevant `04-app-sdk/` files |
 
-Use `auth: 'custom'` or headless `AuthAdapter`. App owns visible login UI. Keep SDK callbacks/data
-only.
+## Data posture
 
-## Implementation Guardrails
+Choose before schema and UI.
 
-- Use `@howone/sdk` typed clients before `raw`.
-- Use `howone.raw` only when typed surface is missing.
-- Do not hardcode HowOne API URLs.
-- Do not pass owner fields for authenticated own records.
-- Do not import or create SDK toast APIs.
-- Do not remove HowOne floating logo unless explicitly requested.
-- Do not call AI workflows from render.
-- Do not persist workflow envelopes or UI-only fields.
-- Do not assume unavailable AI capabilities.
+| Product need | Access | SDK pattern |
+|---|---|---|
+| Per-user private data | authenticated own | `howone.entities.*.query.mine()` |
+| Shared authenticated data | authenticated all | `howone.entities.*.query()` |
+| Public catalog | public list where safe | `howone.public.entities.*.query()` |
+| Public share/detail | public scoped | `howone.public.entities.*.queryScoped()` |
+| Anonymous create | public create scoped/any | `howone.public.entities.*.create()` |
+| AI run history | authenticated own | persist via entity + `query.mine()` |
+| AI public share | private + public scoped entities | two entities |
 
-## Final Architecture Checklist
+Defaults: "my/private" → own; public catalog only when fields are safe; share links → scoped + limits.
 
-Before writing final code:
+## Auth posture
 
-- Data posture is explicit.
-- Auth mode is explicit.
-- Public access has filters/sorts/scopes/limits.
-- AI capability is supported by service catalog.
-- Workflow count follows one-feature rule or RAG exception.
-- Persistence is separate from AI workflow.
-- Manifests are synced before SDK codegen.
-- `src/lib/sdk.ts` is the only app SDK entrypoint.
-- UI owns visible states and feedback.
+| Need | Client | Provider |
+|---|---|---|
+| Hosted HowOne login | default `createClient` | hosted |
+| Custom login UI | `auth: 'custom'`, provider `auth="none"` | app UI |
+| External IdP | headless + adapter | adapter owns token |
+| No auth | `auth: 'none'` | — |
+
+Keep default HowOne brand control unless user asks to hide. SDK exposes data/callbacks—not app toasts or overlays. Resolve user with `me()` / `requireMe()` when data depends on identity.
+
+## Entity workflow (when `02-entity-schema/` in scope)
+
+1. Read schema design + operations references.
+2. Inspect current schema/manifest.
+3. Design full entity contract (fields, access, indexes).
+4. Preview → apply patch → `sync_schema_artifacts`.
+5. Read `{appRoot}/.howone/database/manifest.json`.
+6. Update `src/lib/sdk.ts` per `02-manifest-codegen.md`.
+7. UI via `howone.entities.*` / public namespace; validate.
+
+High-risk changes (delete entity/field, broaden public write, required without default) need explicit user alignment.
+
+## AI workflow (when `03-ai-capabilities/` in scope)
+
+1. Read architecture + **catalog** (feasibility) + contract rules; use playbooks when they match.
+2. Preview → apply capability patch → `sync_ai_artifacts`.
+3. External workflow create/update per workflow-operations reference; keep status IDs from tool results.
+4. Read `{appRoot}/.howone/ai/manifest.json`.
+5. Update `src/lib/sdk.ts` per `08-ai-manifest-handoff.md`; UI via `howone.ai.*`.
+6. If persistence required: entity workflow after output contract is fixed.
+
+Do not fake catalog-backed AI. Platform gap → stop AI design path, explain generically.
+
+## Scope patterns (not a product catalog)
+
+| Pattern | Platform work |
+|---|---|
+| Ephemeral AI result in UI state only | AI + SDK; skip entity-schema unless user adds storage |
+| AI with history/library | AI contract first, then persistence entity |
+| Public view of private AI output | private entity + scoped public entity |
+| Behavior-only AI change | workflow update when schemas unchanged |
+| Schema/UI drift | schema → sync → SDK → then UI |
+
+## Checklist before implementation
+
+- [ ] Scope explicit: which tracks apply; app-owned vs platform clear
+- [ ] Data and auth posture chosen when data in scope
+- [ ] AI requirements verified against catalog when AI in scope
+- [ ] Manifests synced before SDK codegen
+- [ ] `src/lib/sdk.ts` is the HowOne entrypoint
+- [ ] UI owns visible feedback; no invented platform APIs

package/templates/vite/.howone/skills/howone/{02-database → 02-entity-schema}/01-schema-design.md

@@ -1,12 +1,14 @@
 # Database Schema Design
 
+**Track:** `02-entity-schema/` — platform entity contracts only; skip when the user needs no HowOne persisted data.
+
 Use this reference when designing or changing HowOne backend entity schemas. It condenses the
 runtime contract from `docs/dynamic-entity-architecture.zh.md` into instructions an AI agent can
 actually apply.
 
 This file answers: **what should the schema be?** For how to apply changes, read
 `02-schema-operations.md`. For frontend calls, read `03-data-access-patterns.md` and
-`03-sdk/02-entity-operations.md`.
+`04-app-sdk/02-entity-operations.md`.
 
 ## Mental Model
 

package/templates/vite/.howone/skills/howone/{04-ai → 03-ai-capabilities}/01-ai-capability-architecture.md

@@ -1,11 +1,12 @@
 # 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.
+**Track:** `03-ai-capabilities/` — capability/workflow **design** only; SDK calls live in `04-app-sdk/`.
+
+Use this reference when the user needs HowOne platform AI (verify `03-service-capability-catalog.md` first).
 
 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`.
+`04-workflow-operations.md`.
 
 ## Platform Mental Model
 
@@ -46,7 +47,7 @@ Never generate SDK bindings from the user prompt or from an unsynced draft.
 
 Use this flow for new AI features:
 
-1. Classify the feature using `04-ai/04-service-capability-catalog.md`.
+1. Classify the feature using `03-ai-capabilities/03-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`.
@@ -56,7 +57,7 @@ Use this flow for new AI features:
 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`.
+11. Generate/update `src/lib/sdk.ts` using `04-app-sdk/08-ai-manifest-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.
 

package/templates/vite/.howone/skills/howone/{04-ai/04-service-capability-catalog.md → 03-ai-capabilities/03-service-capability-catalog.md}

@@ -1,7 +1,11 @@
 # Service Capability Catalog
 
-Use this reference before designing an AI workflow. It tells the agent what the current workflow
-service can actually do and what input/output shapes are expected.
+Use this reference **only** for HowOne **workflow-service AI** feasibility. It lists what the current
+workflow service supports—not everything a full product may use.
+
+Infrastructure or products the user operates themselves (clusters, custom servers, third-party
+APIs, etc.) are **app-owned** per `01-architect/01-app-generation.md`. They are out of scope for
+this catalog and must not be rejected as "AI not supported" when the user only needs to connect to them in app code.
 
 Source: `docs/ai-capability.md`.
 
@@ -268,14 +272,14 @@ Rules:
 | Video -> Image edit -> Video | extract frame, edit frame, use as next reference |
 | RAG document chat | indexing workflow + query workflow |
 
-## Capability Rejection Checklist
+## Platform AI stop (catalog boundary)
+
+Stop **platform AI design** (do not invent capabilities) when the requirement:
 
-Stop or narrow scope if user requires:
+- has no matching capability family in this catalog or detailed sections below;
+- needs behavior the workflow service cannot perform per contract rules in `02-workflow-contract-rules.md`;
+- violates workflow input/output constraints (e.g. persistence or app CRUD inside the workflow contract);
+- exceeds documented service limits after you read the relevant section.
 
-- real-time streaming market data;
-- arbitrary external API calls not listed;
-- raw file bytes/base64 in workflow;
-- database CRUD inside workflow;
-- unsupported provider-specific model guarantees;
-- content disallowed by moderation;
-- long video generation in one call beyond service limits.
+Explain the gap by **missing catalog/contract support**, not by naming the user's stack. Offer the
+closest listed capability or ask to narrow the product ask. App-owned integrations remain allowed in parallel.

package/templates/vite/.howone/skills/howone/{03-sdk → 04-app-sdk}/01-client-setup.md

@@ -1,5 +1,7 @@
 # Client Setup
 
+**Track:** `04-app-sdk/` — implement HowOne in the app from synced manifests; not schema/AI design.
+
 ## createClient
 
 `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).
@@ -85,7 +87,7 @@ client.schema.restore(versionId, reason?)
 // AI action runner (low-level)
 client.ai: AiClient
 
-// HTTP utilities (low-level — see 03-sdk/06-raw-http.md)
+// HTTP utilities (low-level — see 04-app-sdk/06-raw-http.md)
 client.raw: RawHttpClient
 
 // File upload
@@ -139,7 +141,7 @@ const client = createClient({
 })
 
 // ── 2. Define entity types & bind ────────────────────────────
-// (see 03-sdk/02-entity-operations.md for full details)
+// (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>
@@ -149,7 +151,7 @@ export const entities = defineEntities({
 })
 
 // ── 3. Define AI actions ─────────────────────────────────────
-// (see 03-sdk/07-ai-action-calls.md for full details)
+// (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>
 
@@ -202,7 +204,7 @@ Rules:
 
 ## Auth Modes
 
-See `03-sdk/03-auth.md` for the full custom-login playbook.
+See `04-app-sdk/03-auth.md` for the full custom-login playbook.
 
 ```ts
 // Default — HowOne hosted login (howone.dev / howone.ai)

package/templates/vite/.howone/skills/howone/{03-sdk → 04-app-sdk}/07-ai-action-calls.md

@@ -4,7 +4,7 @@
 
 **`src/lib/sdk.ts` must be generated from `.howone/ai/manifest.json`. Do not write it from memory or from generic examples.**
 
-For AI capability and workflow design, read `04-ai/` first. This file is only for app-side SDK
+For AI capability and workflow design, read `03-ai-capabilities/` first. This file is only for app-side SDK
 bindings and runtime calls after the manifest exists.
 
 For every capability in `manifest.json`:
@@ -98,7 +98,7 @@ type AiEvent = {
 ```
 
 Stream terminates after exactly one of: `run_complete`, `credit_insufficient`, or `run_error`.
-For the full wire protocol, read `03-sdk/09-workflow-execute-sse.md`.
+For the full wire protocol, read `04-app-sdk/10-workflow-execute-sse.md`.
 
 ---
 
@@ -419,7 +419,7 @@ try {
 ## AI Result Persistence
 
 When AI-generated content should be saved to an entity, prefer the SDK persistence helper for
-history-style products. It standardizes the pending-first pattern from `02-database/05-ai-persistence-patterns.md`
+history-style products. It standardizes the pending-first pattern from `02-entity-schema/05-ai-persistence-patterns.md`
 without adding UI behavior.
 
 ```ts

package/templates/vite/.howone/skills/howone/{04-ai/03-ai-sdk-handoff.md → 04-app-sdk/08-ai-manifest-handoff.md}

@@ -1,4 +1,4 @@
-# AI SDK Handoff
+# AI Manifest Handoff (App SDK)
 
 Use this reference after AI capability artifacts have been synced and app code must call the
 workflow through `@howone/sdk`.
@@ -6,7 +6,7 @@ workflow through `@howone/sdk`.
 This file answers: **how does `.howone/ai/manifest.json` become `src/lib/sdk.ts`, and how should UI
 call it?**
 
-For live stream wire details, read `03-sdk/09-workflow-execute-sse.md`. The current endpoint emits
+For live stream wire details, read `04-app-sdk/10-workflow-execute-sse.md`. The current endpoint emits
 only `run_start`, `progress`, `run_complete`, `run_error`, and `credit_insufficient`.
 
 ## Binding Source

package/templates/vite/.howone/skills/howone/SKILL.md

@@ -1,143 +1,110 @@
 ---
 name: howone
-description: Operating manual for HowOne generated app architecture and runtime contracts. Use when a task touches app generation flow, backend/dynamic entity schema design, data access, SDK bindings, frontend code that uses HowOne data, auth, uploads, public/private access, AI capabilities/workflows, AI result persistence, realtime/status/event flows, or any @howone/sdk / howone.entities / howone.public / howone.ai calls. Load first, then read the smallest relevant numbered track: 01-architect, 02-database, 03-sdk, or 04-ai.
+description: HowOne generated app platform. Scope follows the user request. Load for architecture; add entity-schema, ai-capabilities, or app-sdk tracks only when those surfaces are needed.
 ---
 
-# HowOne App Architecture Skill
+# HowOne Skill
 
-This skill is the operating manual for generated HowOne apps. Use it before making platform
-decisions for backend data, frontend data access, auth, AI capabilities, SDK bindings, or generated
-app code that depends on HowOne runtime behavior.
+HowOne apps may be frontend-only, full-stack without AI, AI without custom backend, or full-stack
+with AI and persisted data. **Scope always follows the user's request.** This file is the index;
+processors defer here.
 
-Load the smallest set of numbered references that match the task, but do not skip this skill for
-backend schema design, frontend implementation, or AI features. The references define the contracts
-that app code must follow.
+## Mandatory flow
 
-## Active Tracks
+1. `skill(name="howone")`
+2. `skill_read "01-architect/01-app-generation.md"` — always, before any platform design write
+3. `skill_read` the smallest set from the track index below that architect routing selects
+4. Platform design tools → sync → `{appRoot}/src/lib/sdk.ts` / app code — only for surfaces in scope
 
-| Track | Folder | Use For |
+Inspect-only platform calls do not replace step 2 before the first design write.
+
+## Tracks
+
+| Track | When needed | Design vs implement |
 |---|---|---|
-| `01-architect/` | App generation + manifest flow | End-to-end HowOne app generation flow: when to design backend, when to sync manifests, when to update SDK bindings, and how to choose auth/data posture. |
-| `02-database/` | Backend schema + data access design | Entity schema contract, schema operations, access modes, owner/public data posture, indexes, query DSL, AI output persistence, versions, and guardrails. |
-| `03-sdk/` | Frontend SDK usage | `src/lib/sdk.ts`, auth, React provider, entity calls, public data, uploads, raw HTTP, AI action calls. |
-| `04-ai/` | AI capability + workflow design | HowOne AI capability contracts, service capability selection, workflow create/update/status, schema rules, playbooks, persistence boundaries, and SDK handoff. |
+| `01-architect/` | Always (scope, feasibility, posture, order) | Plan |
+| `02-entity-schema/` | User needs HowOne persisted data | Design contracts |
+| `03-ai-capabilities/` | User needs HowOne AI | Design contracts |
+| `04-app-sdk/` | User calls HowOne via SDK after sync | Implement |
 
-## Routing
+## Platform boundary (read architect for detail)
+
+HowOne platform work must map to **contract evidence**: database manifest, AI manifest, AI service
+catalog, platform tool schemas, or a documented `04-app-sdk/` reference.
+
+| Class | Meaning | Agent action |
+|---|---|---|
+| Platform in scope | Ask is expressible through the surfaces above | Use matching track + design tools |
+| App-owned | User's own ops stack, services, or infra (any technology) | Implement in `{appRoot}` app code/config; do not block |
+| Platform gap | User wants a **platform** feature with no contract evidence | Stop platform path; explain missing surface; Support Policy if needed |
+
+Do not treat unrelated user infrastructure (orchestration, custom servers, third-party products, etc.) as platform stop-loss. Do not model app-owned systems as fake HowOne entities or AI capabilities.
+
+## Track index (skill_read paths)
+
+Read only files required for the current request.
+
+### `01-architect/`
+
+| File | Use for |
+|---|---|
+| `01-app-generation.md` | Scope, platform vs app-owned, feasibility, data/auth posture, workflows, checklist |
+| `02-manifest-codegen.md` | Generate `src/lib/sdk.ts` from synced manifests |
+
+### `02-entity-schema/`
+
+| File | Use for |
+|---|---|
+| `01-schema-design.md` | Entity contract shape, fields, access, indexes |
+| `02-schema-operations.md` | Preview/apply schema patches, versions |
+| `03-data-access-patterns.md` | Public/private/own access, sharing |
+| `04-query-dsl-and-responses.md` | Filters, sort, pagination, response mapping |
+| `05-ai-persistence-patterns.md` | Storing AI results in entities |
+
+### `03-ai-capabilities/`
 
-Read references by task shape. Prefer exact references over generic examples.
-
-- New HowOne app or broad feature planning: read `01-architect/01-app-generation.md`.
-- Any feature touching backend data, frontend data access, or saved records: read the architect
-  flow first, then the relevant database and SDK references below.
-- Any feature touching AI generation, AI workflow behavior, or AI outputs: read the AI references
-  first, then the SDK handoff/action-call references.
-- AI capability, AI workflow generation/editing, or full-stack AI feature planning: read
-  `04-ai/01-ai-capability-architecture.md`, `04-ai/04-service-capability-catalog.md`, and
-  `04-ai/02-workflow-contract-rules.md`.
-- Backend database/schema creation or change: read `02-database/01-schema-design.md` and
-  `02-database/02-schema-operations.md`.
-- AI output persistence, generation history, retry/resume, or saved AI results: read the `04-ai/`
-  files first, then `02-database/05-ai-persistence-patterns.md` and
-  `02-database/01-schema-design.md`.
-- After schema sync, when app code must call the entity: read
-  `01-architect/02-manifest-codegen.md` and `03-sdk/02-entity-operations.md`.
-- Custom login page (your UI, HowOne APIs): `auth: 'custom'` in `createClient` (see `03-sdk/03-auth.md`),
-  `HowOneProvider auth="none"` and keep the default bottom-right HowOne logo unless explicitly hidden. Default without `auth` = hosted HowOne login.
-- `src/lib/sdk.ts`, `createClient`, env vars, or generated bindings: read
-  `03-sdk/01-client-setup.md` and `01-architect/02-manifest-codegen.md`.
-- Public landing pages or share URLs: read `02-database/03-data-access-patterns.md`,
-  `03-sdk/02-entity-operations.md`, and `01-architect/02-manifest-codegen.md`.
-- File upload: read `03-sdk/05-file-upload.md`.
-- Raw HTTP escape hatch: read `03-sdk/06-raw-http.md`.
-- App-side AI action calls after `.howone/ai/manifest.json` exists: read
-  `03-sdk/07-ai-action-calls.md` and `03-sdk/09-workflow-execute-sse.md`.
-- External workflow create/update/status: read `04-ai/05-workflow-operations.md`.
-- Common AI feature templates: read `04-ai/06-ai-feature-playbooks.md`.
-
-## Reference Selection Protocol
-
-Before writing code, classify the touched surfaces:
-
-| Touched surface | Required references |
+| File | Use for |
 |---|---|
-| New app, feature architecture, or uncertain data posture | `01-architect/01-app-generation.md` |
-| Entity/schema/access/index change | `02-database/01-schema-design.md`, `02-database/02-schema-operations.md` |
-| Existing synced manifest to TypeScript bindings | `01-architect/02-manifest-codegen.md` |
-| UI reads/writes entities | `03-sdk/01-client-setup.md`, `03-sdk/02-entity-operations.md` |
-| Public read/share flow | `02-database/03-data-access-patterns.md`, `03-sdk/02-entity-operations.md` |
-| Query filters/sort/pagination/response mapping | `02-database/04-query-dsl-and-responses.md` |
-| AI output persistence / generation history | `02-database/05-ai-persistence-patterns.md`, `04-ai/01-ai-capability-architecture.md` |
-| Auth/session/login behavior | `03-sdk/03-auth.md`, `03-sdk/04-react-integration.md` |
-| AI capability or workflow design | `04-ai/01-ai-capability-architecture.md`, `04-ai/04-service-capability-catalog.md`, `04-ai/02-workflow-contract-rules.md` |
-| External workflow create/update/status | `04-ai/05-workflow-operations.md` |
-| Common AI feature examples | `04-ai/06-ai-feature-playbooks.md` |
-| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md`, `03-sdk/09-workflow-execute-sse.md` |
-| File upload | `03-sdk/05-file-upload.md` |
-| Raw HTTP escape hatch | `03-sdk/06-raw-http.md` |
-| SDK extensibility / adapter boundaries | `03-sdk/08-extension-boundaries.md` |
-
-If a task spans multiple surfaces, read one reference from each surface before editing. Do not
-invent API parameters, response shapes, owner fields, workflow IDs, or output paths from memory.
-
-## Core Workflow
-
-For app features that touch backend data:
-
-1. Decide the data posture in the architect track: private user data, authenticated shared data,
-   public list data, or public scoped share data.
-2. Design or update the entity contract in the database track.
-3. Use schema tools to preview/apply the same operations, then sync schema artifacts.
-4. Read `.howone/database/manifest.json`.
-5. Generate or update app SDK bindings from the manifest.
-6. Implement frontend calls using the SDK track.
-7. Validate with the app's typecheck/build.
-
-For app features that touch AI:
-
-1. Decide the AI feature boundary in the AI track: one workflow per feature, except RAG uses
-   indexing and query workflows.
-2. Design or update the AI capability contract with `ai-capability-design`.
-3. Preview/apply the same AI patch, then sync AI artifacts.
-4. Submit external workflow create/update with `external-ai-capability`.
-5. Preserve returned request IDs for the workflow status/background-task layer.
-6. Read `.howone/ai/manifest.json`.
-7. Generate or update app SDK bindings from the manifest.
-8. Implement frontend calls using `howone.ai.*`.
-9. If outputs are saved, map only durable product fields from the AI result into an entity schema,
-   then follow the database workflow.
-
-For frontend-only SDK work:
-
-1. Read existing `src/lib/sdk.ts`.
-2. Read only the SDK reference for the touched surface.
-3. Preserve existing generated bindings and import style.
-4. Validate.
-
-## Non-Negotiable Rules
-
-- Generate SDK bindings from synced manifests, not from memory.
-- Keep `.howone/` as manifest storage only; do not write generated source files there.
-- Configure `projectId` and `env` only in `createClient`. Auth APIs follow the same `env` (dev → `api.howone.dev`, not `api.howone.ai`).
-- Import `src/lib/sdk.ts` before any `@howone/sdk` auth call so environment is pinned.
-- Use `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`; do not
-  hardcode project IDs or add fallback env values.
-- For private user-owned data, authenticated APIs derive owner from JWT. Do not pass
-  `created_by_id`, `created_by_user_id`, `createdById`, `ownerId`, or `puid`.
-- For `access.authenticated.read = "own"`, prefer `howone.entities.Entity.query.mine(...)`.
-- Public pages use `howone.public.entities.*` only when manifest access explicitly allows public
-  reads or writes.
-- Default `createClient({ projectId, env })` uses **HowOne hosted login**. For a custom `/login` UI
-  that still calls HowOne OTP/OAuth APIs, add `auth: 'custom'` and `HowOneProvider auth="none"`.
-- `HowOneProvider` may render the bottom-right HowOne `FloatingButton` logo by default. Do not remove
-  it unless the user explicitly asks for `brand="hidden"` or `showBrandButton={false}`.
-- Do not add SDK-owned toast APIs, redirect overlays, or app-specific UI. Expose data, state, events,
-  and callbacks; implement visible feedback in the generated frontend app.
-- SDK extensibility rule: default behavior must work without configuration, and custom behavior must
-  enter through typed adapters/callbacks instead of hardcoded app UI or provider-specific branches.
-- AI workflows are implementation, not persistence. Never put CRUD, auth, upload handling, or app
-  state management into the workflow capability contract.
-- For external workflow edits, pass `workflowConfigID` from a confirmed workflow status result; do
-  not invent it or omit it.
-- If the user explicitly requires AI behavior that the available workflow service cannot support,
-  stop that AI implementation path and report the unsupported requirement instead of faking,
-  silently omitting, or replacing the AI capability with static behavior.
+| `01-ai-capability-architecture.md` | Layers, boundaries, feature flow |
+| `02-workflow-contract-rules.md` | Input/output JSON schemas for capabilities |
+| `03-service-capability-catalog.md` | What the workflow service supports (feasibility) |
+| `04-workflow-operations.md` | External workflow create/update/status |
+| `05-ai-feature-playbooks.md` | Recurring product patterns |
+
+### `04-app-sdk/`
+
+| File | Use for |
+|---|---|
+| `01-client-setup.md` | `createClient`, env, provider |
+| `02-entity-operations.md` | `howone.entities` / public namespace |
+| `03-auth.md` | Login, session, custom auth |
+| `04-react-integration.md` | `HowOneProvider`, hooks |
+| `05-file-upload.md` | Uploads |
+| `06-raw-http.md` | Typed escape hatch |
+| `07-ai-action-calls.md` | `howone.ai.*` runtime calls |
+| `08-ai-manifest-handoff.md` | AI manifest → `src/lib/sdk.ts` |
+| `09-extension-boundaries.md` | Adapters, extension rules |
+| `10-workflow-execute-sse.md` | Documented workflow status/streaming wire format |
+
+## Routing
+
+All surface classification and minimum reads live in `01-architect/01-app-generation.md`. This
+skill index lists files; architect decides which apply.
+
+Mixed scope: read at least one file per touched track before writing.
+
+## Design order
+
+```text
+architect → (optional) entity-schema and/or ai-capabilities → sync → app-sdk → UI
+```
+
+Skip tracks the user did not require.
+
+## Rules
+
+- When platform contracts apply: synced `{appRoot}/.howone/database/manifest.json` and/or
+  `{appRoot}/.howone/ai/manifest.json` plus tool results are source of truth.
+- `.howone/` holds manifests only—not generated app source.
+- Do not invent platform schemas, APIs, or identifiers absent from contracts/catalog/tools.
+- Platform stop-loss: architect. User-owned external systems: integrate in app code.

package/templates/vite/.howone/skills/howone/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "HowOne App Architecture"
-  short_description: "Design HowOne database schemas, AI workflows, SDK bindings, auth, and app integration."
-  default_prompt: "Use this skill to choose the right HowOne architecture track, then implement database schema, AI capability/workflow, SDK bindings, auth, or frontend SDK calls from synced manifests."
+  display_name: "HowOne"
+  short_description: "Generated app platform: scope-first architecture, optional entity schema, AI capabilities, and SDK integration from synced contracts."
+  default_prompt: "Load howone, read 01-architect/01-app-generation.md, then the smallest track files from SKILL.md for this request. Scope follows the user—not every app needs AI or backend."

package/templates/vite/AGENTS.md

@@ -69,8 +69,8 @@ Prefer failure-driven inspection over speculative context loading.
 ## HowOne Runtime and Auth
 
 - Use synced HowOne manifests plus `src/lib/sdk.ts` as the source of truth for generated entity and AI bindings.
-- Use the `howone-sdk` skill for HowOne app architecture, backend database schema design, manifest-to-SDK binding, and app-side SDK code.
-- Inside `howone-sdk`, read the smallest relevant numbered track: `01-architect/` for app flow, `02-database/` for schema/access/data design, and `03-sdk/` for frontend SDK/auth/entity calls.
+- Use the `howone` skill: `skill(howone)` → `SKILL.md` → `01-architect/01-app-generation.md` → smallest track reads from the skill index. Scope follows the user request.
+- Tracks: `01-architect/`, `02-entity-schema/`, `03-ai-capabilities/`, `04-app-sdk/` — include only what the user needs.
 - Choose auth posture from the schema access contract, not from guesswork:
   - authenticated/private app data uses `howone.entities.*`; the backend derives ownership from the JWT
   - public pages use `howone.public.entities.*` only when the manifest explicitly allows public access