howone 0.1.31 → 0.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.31",
+  "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

@@ -4,8 +4,9 @@ Read immediately after `skill(name="howone")` and before platform design tools,
 edits, or implementation guesses.
 
 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.
+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.
 
 ## Scope classification
 
@@ -14,9 +15,9 @@ Map the user request to surfaces. Include only what they need.
 | Need | Tracks | Notes |
 |---|---|---|
 | 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 |
+| 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 |
 
@@ -76,9 +77,9 @@ Inspect-only platform reads do not replace this file before the first **design w
 
 | 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 |
+| 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 |
 
 Validated/synced manifests drive code—not prompts or memory.
@@ -87,7 +88,8 @@ Validated/synced manifests drive code—not prompts or memory.
 user request → scope → platform contracts → sync → sdk binding → UI
 ```
 
-Import `howone` from `src/lib/sdk.ts`; do not guess entity/action names or platform URLs.
+When SDK work is in scope, import the app runtime from `src/lib/sdk.ts`; do not guess entity/action
+names or platform URLs.
 
 ## Minimum track reads (after this file)
 
@@ -95,9 +97,10 @@ Use `SKILL.md` for the full file index. Typical minimums:
 
 | 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` |
+| 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 |
 
@@ -105,14 +108,14 @@ Use `SKILL.md` for the full file index. Typical minimums:
 
 Choose before schema and UI.
 
-| Product need | Access | SDK pattern |
+| Product need | Access posture | Runtime handoff |
 |---|---|---|
-| 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()` |
+| 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 |
 
 Defaults: "my/private" → own; public catalog only when fields are safe; share links → scoped + limits.
@@ -126,30 +129,33 @@ Defaults: "my/private" → own; public catalog only when fields are safe; share
 | 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.
+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. Preview → apply patch → `sync_schema_artifacts`.
+4. Apply one complete 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.
+6. Stop backend design. Read SDK references only if implementing app calls.
 
-High-risk changes (delete entity/field, broaden public write, required without default) need explicit user alignment.
+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. Preview → apply capability patch → `sync_ai_artifacts`.
-3. External workflow create/update per workflow-operations reference; keep status IDs from tool results.
+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. Update `src/lib/sdk.ts` per `08-ai-manifest-handoff.md`; UI via `howone.ai.*`.
+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)
 

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-entity-schema/01-schema-design.md

@@ -7,7 +7,8 @@ runtime contract from `docs/dynamic-entity-architecture.zh.md` into instructions
 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
+`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
@@ -49,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
 
@@ -229,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
 
@@ -312,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
 
@@ -362,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
 
@@ -408,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
 
@@ -493,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.