howone 0.1.29 → 0.1.31

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