howone 0.2.2 → 0.2.5

package/package.json

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

@@ -104,7 +104,7 @@ Use `SKILL.md` for the full file index. Typical minimums:
 | 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 |
+| Bindings after sync | `02-manifest-codegen.md` + `04-app-sdk/01-client-setup.md` + `04-app-sdk/03-auth.md` + `04-app-sdk/04-react-integration.md` + the operation-specific SDK file |
 
 ## Data posture
 
@@ -126,14 +126,39 @@ Defaults: "my/private" → own; public catalog only when fields are safe; share
 
 | 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'` | — |
+| HowOne AI, uploads, or authenticated/private entities | default `createClient` | `<HowOneProvider client={howone}>`; hosted guard is inherited |
+| Custom HowOne login UI | `auth: 'custom'`, real OTP/OAuth token flow | `<HowOneProvider client={howone}>`; custom guard is inherited |
+| External IdP | headless + adapter | `<HowOneProvider client={howone}>`; adapter owns token |
+| Manifest-approved public entities only | `auth: 'none'` or explicit public client | `<HowOneProvider client={howone}>` with no required guard |
+| No HowOne runtime | no client required | no Provider required |
 
 Keep default HowOne brand control unless user asks to hide. Resolve identity through the SDK track
 when app code depends on the current user.
 
+### Runtime activation invariant
+
+Contract design and app runtime activation are one delivery chain, not independent completion states.
+When the final app uses any `@howone/sdk` runtime surface—including a synced entity or AI binding,
+public entities, uploads, auth, user/session APIs, or raw SDK requests:
+
+1. Initialize the single app client in `src/lib/sdk.ts` with the generated project/env configuration.
+2. Import that SDK module before `HowOneProvider` and pass the composed client so the Provider sees
+   the selected environment and instance-scoped auth state.
+3. Keep `HowOneProvider` around the rendered application root. This is required for every active
+   HowOne SDK runtime, including public-only entity applications; replacing scaffold UI must not
+   remove it.
+4. Select the Provider guard from the table above. Do not use `auth="none"` to silence a missing login
+   flow for AI, uploads, or authenticated entities.
+5. For hosted auth, unauthenticated protected use must redirect through HowOne login. For custom auth,
+   the app must acquire an actual HowOne token and call `howone.auth.setToken()` before protected SDK
+   requests.
+6. Validate the logged-out path and the authenticated SDK call path. A styled login screen, compiled
+   SDK binding, or synced manifest alone does not prove runtime integration.
+
+Pure UI/static work may omit this runtime chain only when the application makes no HowOne runtime
+calls. Public-only entity experiences may stay anonymous only when the synced manifest explicitly
+permits the public operation and app code uses `howone.public.entities.*`.
+
 ## Entity workflow (when `02-entity-schema/` in scope)
 
 1. Read schema design + operations references.
@@ -151,8 +176,8 @@ without default) need explicit user alignment before applying the final patch.
 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. Wait for the terminal result. A successful update promotes its new workflow ID in the backend capability version.
-5. Run `sync_ai_artifacts` again, then read `{appRoot}/.howone/ai/manifest.json`.
+4. Treat submission as asynchronous pending work, not a pause boundary. Continue independent app source, UI, persistence, and state implementation instead of ending the run to wait.
+5. After the terminal result becomes available, run `sync_ai_artifacts` again, then read `{appRoot}/.howone/ai/manifest.json`. A successful update promotes its new workflow ID in the backend capability version.
 6. Stop AI design. Read SDK references only if implementing app calls.
 7. If persistence required: entity workflow after output contract is fixed.
 
@@ -177,4 +202,8 @@ capability patch.
 - [ ] AI requirements verified against catalog when AI in scope
 - [ ] Manifests synced before SDK codegen
 - [ ] `src/lib/sdk.ts` is the HowOne entrypoint
+- [ ] App code uses generated SDK bindings instead of direct internal platform HTTP requests
+- [ ] Active HowOne runtime keeps `HowOneProvider` at the app root and initializes the SDK first
+- [ ] AI, uploads, and authenticated entities have a real hosted/custom/headless token path
+- [ ] Public-only anonymous access is backed by manifest public rules and the public SDK namespace
 - [ ] UI owns visible feedback; no invented platform APIs