howone 0.1.30 → 0.1.32

package/templates/vite/.howone/skills/howone/{04-ai/06-ai-feature-playbooks.md → 03-ai-capabilities/05-ai-feature-playbooks.md}

@@ -1,7 +1,7 @@
 # AI Feature Playbooks
 
-Use this reference when turning a user request into concrete HowOne AI capabilities, database
-entities, and SDK calls.
+Use this reference when turning a user request into concrete HowOne AI capabilities and optional
+persistence entities. App-side SDK calls belong to `04-app-sdk/`.
 
 ## Playbook: Document Summary
 
@@ -47,11 +47,8 @@ Persistence:
 - private `DocumentSummary` if user history is needed;
 - fields: `documentUrl`, `summary`, `status`, `errorMessage`, `requestedAt`, `completedAt`.
 
-SDK:
-
-```ts
-const output = await howone.ai.summarizeDocument.run({ document_url: fileUrl })
-```
+App implementation handoff: after sync and external workflow submit, read the SDK track before
+writing app-side AI runtime calls.
 
 ## Playbook: Image Generator
 
@@ -97,26 +94,8 @@ Persistence:
 - use `Generation` for private history;
 - public share requires separate `SharedGeneration`.
 
-SDK:
-
-```ts
-await runAiActionAndPersist({
-  entity: howone.entities.Generation,
-  input: { image_description, style_preference },
-  createPending: (input) => ({
-    prompt: input.image_description,
-    style: input.style_preference ?? null,
-    status: 'pending',
-    requestedAt: new Date().toISOString(),
-  }),
-  run: (input) => howone.ai.generateImage.run(input),
-  mapCompleted: ({ output }) => ({
-    status: 'completed',
-    resultUrl: output.generated_image_url,
-    completedAt: new Date().toISOString(),
-  }),
-})
-```
+App implementation handoff: if persistence is needed, finish the entity contract first, then read
+the SDK track for runtime action calls and persistence helper usage.
 
 ## Playbook: Image Editor
 
@@ -288,9 +267,9 @@ Rules:
 ## Feature Design Checklist
 
 - Choose one playbook or clearly combine compatible playbooks.
-- Verify capability exists in `04-service-capability-catalog.md`.
+- Verify capability exists in `03-service-capability-catalog.md`.
 - Use URL inputs for files/media.
 - Keep outputs minimal and product-facing.
 - Decide persistence separately.
-- Generate SDK bindings only after manifest sync.
+- Generate SDK bindings only after manifest sync and external workflow submit.
 - Use app-owned UI for progress/errors.

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).
@@ -75,7 +77,6 @@ client.public.raw: RawHttpClient
 client.schema.listDefinitions()
 client.schema.getDefinition(entityName)
 client.schema.operate(operation)
-client.schema.previewPatch(patch, { expectedVersionId, reason })
 client.schema.applyPatch(patch, { expectedVersionId, reason })
 client.schema.getState()
 client.schema.listVersions()
@@ -85,7 +86,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 +140,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 +150,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 +203,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)
@@ -287,7 +288,7 @@ client.auth.logout()
 
 - Use `client.entities.*` / `howone.entities.*` for authenticated app data. The backend derives owner from the JWT; do not pass owner filters or owner fields.
 - Use `client.public.entities.*` / `howone.public.entities.*` for public landing pages, public article lists, scoped QR/profile pages, and public forms.
-- Use `client.schema.*` only for backend contract management: definitions, schema operations, schema patch preview/apply, versions, and restore.
+- Use `client.schema.*` only for backend contract management: definitions, schema operations, schema patch apply, versions, and restore.
 - Use `client.raw.*` only for custom endpoints not covered by typed SDK methods.
 
 ---

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`:
@@ -27,8 +27,8 @@ Correct sequence:
 1. `ai-capability-design` — design the capability contract
 2. `sync_ai_artifacts` — sync manifest to disk
 3. `external-ai-capability` — submit workflow create/update to EAX from the synced manifest
-4. Workflow status/background-task layer confirms readiness and captures `workflowConfigID` for future edits
-5. Read `.howone/ai/manifest.json` → write `src/lib/sdk.ts` with `workflowId`
+4. Re-read `.howone/ai/manifest.json`; update may have rotated `workflowId`
+5. Write `src/lib/sdk.ts` with the current manifest `workflowId`
 
 Building without errors does **not** mean the AI workflow binding is correct. A missing `workflowId` causes a runtime UUID error at the EAX execution call.
 
@@ -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
@@ -217,12 +217,13 @@ Do not ask the workflow to write records. Do not pass owner fields for authentic
 When changing external workflow behavior later:
 
 1. If schema changes, update AI capability contract first and sync manifest.
-2. Use `workflowConfigID` from a completed status result.
-3. Submit update with `capabilityName`, `workflowConfigID`, and `updatePrompt`.
-4. Preserve the new status result and config ID if it changes.
-5. Regenerate SDK only if manifest contract changed.
+2. Submit update through `external-ai-capability` with `updates: [{ capabilityName, updatePrompt }]`.
+3. Re-read `.howone/ai/manifest.json`; update may rotate `workflowId` to a fresh config UUID.
+4. Regenerate SDK bindings whenever the manifest `workflowId`, input schema, or output schema changed.
+5. Behavior-only updates still require checking the manifest before deciding SDK is unchanged.
 
-`workflowConfigID` is not `workflowId`.
+The SDK does not use old `workflowConfigID` status values. It binds to the current manifest
+`workflowId`, which is the EAX config id used in execution URLs.
 
 ## Handoff Checklist
 

package/templates/vite/.howone/skills/howone/{03-sdk/08-extension-boundaries.md → 04-app-sdk/09-extension-boundaries.md}

@@ -61,7 +61,7 @@ Do not add one-off flags when an adapter/callback can express the behavior.
 | 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 |
+| Schema | definition operations, 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 |

package/templates/vite/.howone/skills/howone/{02-database/03-data-access-patterns.md → 04-app-sdk/11-entity-data-access-patterns.md}

@@ -1,10 +1,10 @@
-# Data Access Patterns
+# Entity Data Access Patterns (App SDK)
 
 Use this reference to connect backend `access` design to frontend SDK calls. It answers:
 **which namespace should the app call, which filters are legal, and what must not be persisted?**
 
-For schema design, read `01-schema-design.md`. For query syntax details, read
-`04-query-dsl-and-responses.md`.
+For schema design, read `02-entity-schema/01-schema-design.md`. For query syntax details, read
+`12-query-dsl-and-responses.md`.
 
 ## Namespace Decision
 
@@ -14,7 +14,7 @@ For schema design, read `01-schema-design.md`. For query syntax details, read
 | Logged-in shared records | `howone.entities.Entity` | yes | `query`, `get`, CRUD |
 | Public list page | `howone.public.entities.Entity` | no | `query` |
 | Public scoped share/detail | `howone.public.entities.Entity` | no | `queryScoped`, `get` with scope options |
-| Schema tooling | `howone.schema` | yes | `previewPatch`, `applyPatch` |
+| Schema tooling | `howone.schema` | yes | `applyPatch`, versions, restore |
 | Low-level fallback | `howone.raw` / `howone.public.raw` | depends | only when typed method missing |
 
 Do not mix authenticated and public namespaces for the same page without a clear reason.

package/templates/vite/.howone/skills/howone/{02-database/04-query-dsl-and-responses.md → 04-app-sdk/12-query-dsl-and-responses.md}

@@ -1,4 +1,4 @@
-# Query DSL And Responses
+# Entity Query DSL And Responses (App SDK)
 
 Use this reference when implementing list/detail pages, filters, sorting, pagination, or response
 normalization for HowOne dynamic entities.

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

@@ -1,143 +1,147 @@
 ---
 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: 'Use when the task touches HowOne platform contracts or app runtime: designing/changing backend dynamic entity schemas, public/private access, Mongo-backed persisted data, AI capabilities/workflows, external-ai workflow create/update/status, syncing .howone manifests, generating src/lib/sdk.ts, auth/uploads, or app code that calls @howone/sdk/howone.*. Also use when files mention backend-api-design, ai-capability-design, sync_schema_artifacts, sync_ai_artifacts, external-ai-capability, .howone/database, or .howone/ai. Do not use for UI-only edits with no HowOne data, AI, auth, upload, manifest, or SDK surface.'
 ---
 
-# HowOne App Architecture Skill
+# HowOne
 
-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 builds generated full-stack AI apps. Platform contracts are separate from app implementation:
 
-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.
+- Backend: dynamic entity contracts backed by HowOne's MongoDB runtime.
+- AI: capability contracts and external workflow generation/editing.
+- SDK: app-side runtime bindings and calls after manifests are synced.
 
-## Active Tracks
+Load only the track needed for the user's request. Do not read SDK files while designing backend or AI contracts unless the task has reached manifest-to-code implementation.
 
-| Track | Folder | Use For |
+## Trigger Preconditions
+
+Use this skill before work when any condition is true:
+
+- The user asks for persisted app data, backend schema, entity fields, access, indexes, public pages, private history, or Mongo-backed records.
+- The user asks for HowOne AI behavior, capability contracts, workflow generation/update/status, or `external-ai`.
+- The work reads or writes `.howone/database/*`, `.howone/ai/*`, `src/lib/sdk.ts`, or app code using `@howone/sdk` / `howone.*`.
+- The selected tool is `backend-api-design`, `ai-capability-design`, `sync_schema_artifacts`, `sync_ai_artifacts`, or `external-ai-capability`.
+- The implementation needs HowOne auth, upload URLs, public/private entity access, or manifest-to-SDK bindings.
+
+Skip this skill only when the task is purely UI/static code and does not touch HowOne data, AI,
+auth, upload, manifests, or SDK calls.
+
+## First Decision
+
+Classify the request before tool writes:
+
+| User need | Track | Tools/files |
 |---|---|---|
-| `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. |
-
-## Routing
-
-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 |
+| Persist HowOne app data | Backend | `backend-api-design`, `sync_schema_artifacts`, backend files under `02-entity-schema/` |
+| Add/change HowOne AI behavior | AI | `ai-capability-design`, `sync_ai_artifacts`, `external-ai-capability`, `03-ai-capabilities/*` |
+| Call HowOne from generated app code | SDK | `src/lib/sdk.ts`, synced manifests, `04-app-sdk/*` |
+| UI only, no HowOne data or AI | None | edit app code only |
+| User-owned external services | App-owned | integrate in app code/config; do not fake platform contracts |
+
+If multiple tracks apply, process them in dependency order:
+
+```text
+architect -> backend contract and/or AI contract -> sync manifests -> SDK bindings -> UI
+```
+
+## Mandatory Reads
+
+Always read `01-architect/01-app-generation.md` before the first write to a HowOne platform contract or SDK binding.
+
+Then read the minimum track files:
+
+| Track | Required before writes |
+|---|---|
+| Backend contract | `02-entity-schema/01-schema-design.md`, `02-entity-schema/02-schema-operations.md` |
+| AI contract | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-ai-capabilities/02-workflow-contract-rules.md`, `03-ai-capabilities/03-service-capability-catalog.md` |
+| External AI workflow submit/update | `03-ai-capabilities/04-workflow-operations.md` |
+| SDK binding/code | `01-architect/02-manifest-codegen.md` plus the relevant `04-app-sdk/` file |
+| AI output persistence | Backend required reads plus `02-entity-schema/05-ai-persistence-patterns.md` after AI output schema is known |
+
+Do not load all references preemptively.
+
+## Tool Flow
+
+Backend contract:
+
+```text
+get_current_schema -> apply_schema_patch -> sync_schema_artifacts -> read .howone/database/manifest.json
+```
+
+AI contract:
+
+```text
+get_current_ai_capabilities -> apply_capability_patch -> sync_ai_artifacts -> external-ai-capability -> read .howone/ai/manifest.json
+```
+
+No contract dry-run step. Normal generation applies one well-formed patch directly. For destructive,
+narrowing, or public-access-expanding changes, stop for user alignment first, then apply the exact
+approved patch.
+
+SDK/code:
+
+```text
+read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using src/lib/sdk.ts imports
+```
+
+## Source Of Truth
+
+- Backend fields/access/indexes: `{appRoot}/.howone/database/manifest.json` after sync.
+- AI names/workflow IDs/schemas: `{appRoot}/.howone/ai/manifest.json` after sync.
+- App runtime entry: `{appRoot}/src/lib/sdk.ts`.
+- Do not handwrite `.howone/` metadata.
+- Do not infer contract identifiers from prompts, memory, or dependency source.
+
+## Track Index
+
+### Architect
+
+| File | Use |
+|---|---|
+| `01-architect/01-app-generation.md` | Scope classification, platform boundary, ordering |
+| `01-architect/02-manifest-codegen.md` | Synced manifests to `src/lib/sdk.ts` |
+
+### Backend
+
+| File | Use |
+|---|---|
+| `02-entity-schema/01-schema-design.md` | Entity fields, access, indexes |
+| `02-entity-schema/02-schema-operations.md` | Patch/apply/sync/version rules |
+| `02-entity-schema/03-access-models.md` | Backend authenticated/public access models |
+| `02-entity-schema/04-query-contracts.md` | Backend filter/sort/pagination/index contracts |
+| `02-entity-schema/05-ai-persistence-patterns.md` | Saving AI results into entities |
+
+### AI
+
+| File | Use |
+|---|---|
+| `03-ai-capabilities/01-ai-capability-architecture.md` | AI layers and design order |
+| `03-ai-capabilities/02-workflow-contract-rules.md` | Capability JSON schema rules |
+| `03-ai-capabilities/03-service-capability-catalog.md` | Supported workflow families |
+| `03-ai-capabilities/04-workflow-operations.md` | External workflow create/update/status |
+| `03-ai-capabilities/05-ai-feature-playbooks.md` | Reusable AI product patterns |
+
+### SDK
+
+| File | Use |
 |---|---|
-| 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.
+| `04-app-sdk/01-client-setup.md` | `createClient`, env, provider |
+| `04-app-sdk/02-entity-operations.md` | `howone.entities` and public namespace |
+| `04-app-sdk/03-auth.md` | Login/session/custom auth |
+| `04-app-sdk/04-react-integration.md` | Provider and hooks |
+| `04-app-sdk/05-file-upload.md` | Upload URLs/files |
+| `04-app-sdk/06-raw-http.md` | Typed escape hatch |
+| `04-app-sdk/07-ai-action-calls.md` | `howone.ai.*` runtime calls |
+| `04-app-sdk/08-ai-manifest-handoff.md` | AI manifest to SDK bindings |
+| `04-app-sdk/09-extension-boundaries.md` | Adapter/extension boundaries |
+| `04-app-sdk/10-workflow-execute-sse.md` | Workflow run/stream wire format |
+| `04-app-sdk/11-entity-data-access-patterns.md` | App entity access calls from synced manifest |
+| `04-app-sdk/12-query-dsl-and-responses.md` | App query/filter/sort/pagination calls |
+
+## Hard Rules
+
+- Backend and AI design references must not include SDK implementation work.
+- SDK references must not invent backend or AI contracts; they consume synced manifests.
+- AI workflows must not perform database CRUD; persistence is app code through entities.
+- User-owned infrastructure is app code, not a platform gap.
+- Platform gap means missing HowOne contract/tool/catalog support, not an unsupported technology name.

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