howone 0.1.30 → 0.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "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,177 @@
 # 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**, and routes to backend, AI, or SDK tracks. Keep design
+tracks separate: backend design does not require SDK references; AI design does not require SDK
+references until the synced AI manifest is ready for code.
 
-## 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 | Skip SDK until app code needs calls |
+| HowOne AI features | `03-ai-capabilities/` → sync → external workflow | Verify catalog before design |
+| SDK wiring, auth, UI calls | `04-app-sdk/` | Only 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` | Entity binding handoff |
+| AI | `{appRoot}/.howone/ai/manifest.json` + workflow status | AI binding handoff |
+| SDK | `@howone/sdk` + `{appRoot}/src/lib/sdk.ts` | App runtime 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.
+When SDK work is in scope, import the app runtime 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-entity-schema/02-schema-operations.md` |
+| Backend query/public contracts | add `02-entity-schema/03-access-models.md`, `02-entity-schema/04-query-contracts.md` |
+| App entity query code | add `04-app-sdk/11-entity-data-access-patterns.md`, `04-app-sdk/12-query-dsl-and-responses.md` after manifest sync |
+| AI design | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-ai-capabilities/03-service-capability-catalog.md`, `03-ai-capabilities/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 posture | Runtime handoff |
+|---|---|---|
+| Per-user private data | authenticated own | SDK entity track later |
+| Shared authenticated data | authenticated all | SDK entity track later |
+| Public catalog | public list where safe | SDK public entity track later |
+| Public share/detail | public scoped | SDK public entity track later |
+| Anonymous create | public create scoped/any | SDK public entity track later |
+| AI run history | authenticated own | private history entity |
+| 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. Resolve identity through the SDK track
+when app code depends on the current user.
+
+## 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. Apply one complete patch → `sync_schema_artifacts`.
+5. Read `{appRoot}/.howone/database/manifest.json`.
+6. Stop backend design. Read SDK references only if implementing app calls.
+
+No schema dry-run step. High-risk changes (delete entity/field, broaden public write, required
+without default) need explicit user alignment before applying the final patch.
+
+## AI workflow (when `03-ai-capabilities/` in scope)
+
+1. Read architecture + **catalog** (feasibility) + contract rules; use playbooks when they match.
+2. Apply one complete capability patch → `sync_ai_artifacts`.
+3. External workflow create/update per workflow-operations reference; keep job/request IDs from tool results.
+4. Read `{appRoot}/.howone/ai/manifest.json`.
+5. Stop AI design. Read SDK references only if implementing app calls.
+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.
+No AI capability dry-run step. Design the contract from the skill references, then apply the final
+capability patch.
+
+## 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/01-architect/02-manifest-codegen.md

@@ -15,8 +15,8 @@ Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. T
 
 For AI capabilities, external workflow create/update is submitted by `external-ai-capability` from
 the synced manifest. Do not duplicate AI schemas in app code beyond generated zod/type bindings.
-For workflow edits, `workflowConfigID` belongs to the external workflow operation; it is not an SDK
-binding field.
+For workflow edits, `external-ai-capability` may rotate the manifest `workflowId`; always re-read
+`.howone/ai/manifest.json` after the tool returns before updating `src/lib/sdk.ts`.
 
 ---
 

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

@@ -1,12 +1,15 @@
 # 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`.
+`02-schema-operations.md`. For access/query contract details, read `03-access-models.md` and
+`04-query-contracts.md`. For frontend calls, wait for manifest sync, then read
+`04-app-sdk/02-entity-operations.md`.
 
 ## Mental Model
 
@@ -47,7 +50,7 @@ Each section has a different job:
 | `relations` | Valid include names | What can be joined/expanded? |
 | `presentation` | Admin/generator hints | What fields identify the record in UI? |
 | `lifecycle` | Audit/delete policy hints | Is this append-only, soft-deletable, audited? |
-| `performance` | SDK/admin pagination/sort hints | What limits and sorts are safe? |
+| `performance` | Runtime/admin pagination/sort hints | What limits and sorts are safe? |
 
 ## Storage Reality
 
@@ -227,7 +230,7 @@ Rules:
 - For private user data, use all `own`.
 - For authenticated shared dashboards/CMS, use `read: "all"` and be conservative on update/delete.
 - Do not pass owner fields in authenticated payloads or filters. Backend derives owner from auth.
-- `query.mine()` is the SDK shorthand for authenticated own lists.
+- Authenticated own lists must use the authenticated channel so the backend can derive ownership.
 
 ### Public Access
 
@@ -310,14 +313,7 @@ Use for todos, notes, journals, saved generations, personal settings.
 }
 ```
 
-SDK list:
-
-```ts
-await howone.entities.Todo.query.mine({
-  page: { number: 1, size: 50 },
-  orderBy: { updatedDate: 'desc' },
-})
-```
+App implementation handoff: use the SDK entity operations reference after manifest sync.
 
 ### B. Public Read-Only Catalog
 
@@ -360,15 +356,8 @@ Use for articles, templates, listings, published galleries.
 }
 ```
 
-SDK public list:
-
-```ts
-await howone.public.entities.Article.query({
-  where: { status: 'published' },
-  orderBy: { publishedAt: 'desc' },
-  page: { number: 1, size: 20 },
-})
-```
+App implementation handoff: public list calls are generated from `access.public.allowedFilters`,
+`allowedSorts`, and pagination limits after manifest sync.
 
 ### C. Public Scoped Share Page
 
@@ -406,14 +395,7 @@ Use for QR profile, public invoice, public resume, shared report.
 }
 ```
 
-SDK public scoped read:
-
-```ts
-await howone.public.entities.QrProfile.queryScoped({
-  where: { ownerId, slug, active: true },
-  page: { number: 1, size: 1 },
-})
-```
+App implementation handoff: scoped public reads must include every `requiredScopes` value.
 
 ### D. Workflow Output History
 
@@ -491,7 +473,7 @@ Use `relations` only when frontend/admin needs `include`.
 
 Rules:
 
-- Keep relation names stable; SDK/UI may use them in `include`.
+- Keep relation names stable; app code may use them in `include`.
 - Do not use relations to hide missing denormalized fields required by list pages.
 - Public include should be conservative; ensure related data is safe to expose.