howone 0.1.17 → 0.1.19

package/bin/index.mjs

@@ -1,16 +1,19 @@
 #!/usr/bin/env bun
 import { createRequire } from "node:module";
-import { say, spinner } from "@astrojs/cli-kit";
-import { cancel, confirm, isCancel, select, text } from "@clack/prompts";
+import { execFile } from "node:child_process";
 import { readdir, rename, stat, writeFile } from "node:fs/promises";
-import { copy, emptyDir, ensureDir, pathExists } from "fs-extra/esm";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { say, spinner } from "@astrojs/cli-kit";
+import { cancel, confirm, isCancel, select, text } from "@clack/prompts";
+import { copy, emptyDir, ensureDir, pathExists } from "fs-extra/esm";
 import pc from "picocolors";
 import validatePackageName from "validate-npm-package-name";
 import yargsParser from "yargs-parser";
 //#region src/index.ts
 const packageJson = createRequire(import.meta.url)("../package.json");
+const execFileAsync = promisify(execFile);
 const DEFAULT_PROJECT_NAME = "howone-app";
 const TEMPLATES = ["vite", "nextjs"];
 const TEMPLATE_ALIASES = {
@@ -111,10 +114,13 @@ function compact(values) {
 async function runInitApp(pathArgs, options) {
 	const plan = await resolveCreatePlan(pathArgs, options, path.resolve(options.cwd ?? process.cwd()), process.stdout.isTTY && !options.yes && !options.json);
 	const howoneContext = resolveHowoneCreateContext();
-	if (options.json) await createTemplate(plan, howoneContext, true);
-	else {
+	if (options.json) {
+		await createTemplate(plan, howoneContext, true);
+		await installTemplateDependencies(plan, true);
+	} else {
 		await say(pc.bold("HowOne"));
 		await createTemplate(plan, howoneContext, false);
+		await installTemplateDependencies(plan, false);
 	}
 	const result = {
 		ok: true,
@@ -128,11 +134,7 @@ async function runInitApp(pathArgs, options) {
 			env: howoneContext.env,
 			envFile: path.join(plan.targetDir, ".env")
 		} } : {},
-		nextSteps: [
-			`cd ${formatPathForShell(path.relative(plan.cwd, plan.targetDir) || ".")}`,
-			"bun install",
-			"bun run dev"
-		]
+		nextSteps: [`cd ${formatPathForShell(path.relative(plan.cwd, plan.targetDir) || ".")}`, "bun run dev"]
 	};
 	if (options.json) {
 		console.log(JSON.stringify(result, null, 2));
@@ -291,6 +293,30 @@ async function createTemplate(plan, howoneContext, json) {
 		while: () => performCreateTemplate(plan, howoneContext)
 	});
 }
+async function installTemplateDependencies(plan, json) {
+	const install = async () => {
+		try {
+			await execFileAsync("bun", ["install"], {
+				cwd: plan.targetDir,
+				maxBuffer: 10 * 1024 * 1024
+			});
+		} catch (error) {
+			throw new CliError("E_DEP_INSTALL_FAILED", "Failed to install dependencies with bun.", error && typeof error === "object" ? {
+				stdout: "stdout" in error ? String(error.stdout ?? "") : void 0,
+				stderr: "stderr" in error ? String(error.stderr ?? "") : void 0
+			} : void 0);
+		}
+	};
+	if (json) {
+		await install();
+		return;
+	}
+	await spinner({
+		start: "Installing dependencies with bun",
+		end: "Dependencies installed",
+		while: install
+	});
+}
 async function performCreateTemplate(plan, howoneContext) {
 	const templateDir = getTemplateDir(plan.template);
 	if (plan.force && await pathExists(plan.targetDir)) await emptyDir(plan.targetDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

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

@@ -12,13 +12,13 @@ This skill is the authoritative source of truth for all `@howone/sdk` usage in g
 | Module | File | What It Covers |
 |---|---|---|
 | Client Setup | `references/01-client-setup.md` | `createClient`, env vars, `CreateClientOptions`, all client fields |
-| Entity Operations | `references/02-entity-operations.md` | CRUD, `query`, `list`, `aggregate`, `bulkCreate`, typed records |
+| Entity Operations | `references/02-entity-operations.md` | authenticated CRUD/query, public entity reads/writes, include, pagination, typed records |
 | AI Actions | `references/03-ai-actions.md` | `defineAiAction`, `run`/`stream`/`events`, zod schemas, SSE callbacks |
 | Auth | `references/04-auth.md` | Email OTP, Phone OTP, OAuth (Google/GitHub), token management |
 | File Upload | `references/05-file-upload.md` | `upload.file`, `upload.image`, `upload.batch`, progress, abort |
 | React Integration | `references/06-react-integration.md` | `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading` |
 | Raw HTTP | `references/07-raw-http.md` | `client.raw.*`, custom API calls, interceptors |
-| Manifest Codegen | `references/08-manifest-codegen.md` | Reading `.howone/database` and `.howone/ai`, generating `src/lib/sdk.ts` |
+| Manifest Codegen | `references/08-manifest-codegen.md` | Reading `.howone/database` and `.howone/ai`, generating `src/lib/sdk.ts`, public access-aware types |
 
 ## Workflow
 
@@ -52,6 +52,7 @@ export type TodoRecord = EntityRecord & {
 }
 export type TodoCreate = { title: string; completed: boolean }
 export type TodoUpdate = Partial<TodoCreate>
+export type TodoPublicQuery = { completed?: boolean; limit?: number }
 
 // Schemas
 export const summarizeTodoInputSchema = z.object({ title: z.string().min(1) })
@@ -83,7 +84,14 @@ export default howone
 ## Hard Rules
 
 - **Vite env only**: use `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`. Never hardcode project IDs or add `?? 'prod'` fallbacks.
+- **Single SDK config source**: configure `projectId` and `env` only in `createClient`. Do not pass env/project config to `HowOneProvider`; the React provider reads the SDK config set by `createClient`.
+- **Authenticated owner semantics**: authenticated entity APIs derive owner from the JWT. Do not pass `created_by_id`, `created_by_user_id`, `ownerId`, or `puid` to authenticated queries or writes.
+- **Public namespace**: public reads/writes must use `howone.public.entities.*` or `client.public.entity(...)`. Do not call authenticated `howone.entities.*` from public landing pages.
+- **Public scoped queries**: for `access.public.read = "scoped"`, use `queryScoped` / `query.scoped` and pass every `requiredScopes` field such as `ownerId` and `slug`.
+- **Public writes**: only generate public `create` / `update` calls when manifest access explicitly allows them. Public create must include `created_by_user_id` or the schema-defined owner scope.
 - **Explicit types**: define `EntityRecord`, `Create`, and `Update` types explicitly. Never derive create types from `Omit<EntityRecord & ...>` — it widens the payload.
+- **System fields**: never include `id`, `_id`, `created_date`, `updated_date`, `created_by_id`, `schema_version_id`, `schema_version_number`, or `is_sample` in create/update input types.
+- **Schema versions**: treat `schemaVersionId` / `schemaVersionNumber` on records as write-time schema metadata, not business versioning.
 - **AI action naming**: do not name actions `run`, `stream`, or `events` — those are reserved method names.
 - **Call shape**: `howone.ai.<actionName>.run(input)` / `.stream(input)` / `.events(input)`. Never `howone.ai.run.<actionName>(input)`.
 - **No hooks**: `@howone/sdk/react` provides auth/theme/loading UI only — no entity, query, or AI data hooks.

package/templates/vite/.howone/skills/howone-sdk/references/01-client-setup.md

@@ -67,6 +67,22 @@ client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient
 // Typed entity map (populated via withEntities)
 client.entities: Record<string, EntityClient>
 
+// Public entity namespace (never sends Authorization)
+client.public.entity<TRecord, TPublicCreate, TPublicUpdate>(entityName: string): PublicEntityClient
+client.public.entities: Record<string, PublicEntityClient>
+client.public.raw: RawHttpClient
+
+// Schema contract/version client
+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()
+client.schema.getVersion(versionId)
+client.schema.restore(versionId, reason?)
+
 // AI action runner (low-level)
 client.ai: AiClient
 
@@ -215,9 +231,12 @@ const client = createClient({
 ```ts
 type UserProfile = {
   id: string
+  userId?: string
+  puid?: string
   email?: string
   name?: string
   avatarUrl?: string
+  appId?: string
   roles?: string[]
   metadata?: Record<string, unknown>
 }
@@ -242,6 +261,15 @@ client.auth.logout()
 
 ---
 
+## Client Namespace Rules
+
+- 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.raw.*` only for custom endpoints not covered by typed SDK methods.
+
+---
+
 ## HowOneAuthError
 
 ```ts

package/templates/vite/.howone/skills/howone-sdk/references/02-entity-operations.md

@@ -18,7 +18,9 @@ type EntityRecord = {
   id: string
   createdDate?: string
   updatedDate?: string
-  createdById?: string
+  createdById?: string  // backend owner id from created_by_id
+  schemaVersionId?: string
+  schemaVersionNumber?: number
   isSample?: boolean
   [key: string]: unknown   // index signature — important for typing
 }
@@ -105,6 +107,25 @@ type DeleteResult = {
 }
 ```
 
+## PublicEntityClient API
+
+Public entity calls use `/api/entities/public/apps/:appId/...` and do not send auth headers.
+Only use them when the entity manifest explicitly allows `access.public.read`,
+`access.public.create`, or `access.public.update`.
+
+```ts
+type PublicEntityClient<TRecord, TPublicCreate, TPublicUpdate> = {
+  name: string
+  query(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  query.scoped(options: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  queryScoped(options: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  get(id: string, options?: QueryOptions<TRecord>): Promise<TRecord | null>
+  getOrThrow(id: string, options?: QueryOptions<TRecord>): Promise<TRecord>
+  create(data: TPublicCreate): Promise<TRecord>
+  update(id: string, data: TPublicUpdate): Promise<TRecord>
+}
+```
+
 ---
 
 ## CRUD Examples
@@ -208,7 +229,12 @@ const result = await howone.entities.Story.query({
 })
 ```
 
-### query.mine — only current user's records
+### query.mine — current authenticated user's records
+
+`query.mine()` is the preferred way to fetch records owned by the authenticated user.
+It requires a valid auth token, then lets the backend derive owner from the JWT. Do not
+manually pass `created_by_id`, `created_by_user_id`, `ownerId`, or `puid` in authenticated
+queries or writes.
 
 ```ts
 const myStories = await howone.entities.Story.query.mine({
@@ -217,6 +243,18 @@ const myStories = await howone.entities.Story.query.mine({
 })
 ```
 
+For public pages that cannot use the current auth session, switch to `howone.public`.
+The public endpoint is controlled by `access.public.allowedFilters` and
+`access.public.requiredScopes`:
+
+```ts
+const result = await howone.public.entities.Story.query({
+  published: true,
+  page: { number: 1, size: 20 },
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
 ### WhereInput — field operators
 
 ```ts
@@ -246,6 +284,18 @@ const result = await howone.entities.Story.query({
 })
 ```
 
+### Include relations
+
+`include` accepts a string or string array. All entities support `include: 'user'`.
+Entity-specific relation names must come from the manifest `relations` contract.
+
+```ts
+const result = await howone.entities.Story.query({
+  include: ['user', 'author'],
+  page: { number: 1, size: 20 },
+})
+```
+
 ---
 
 ## list() — Simple Array Read
@@ -268,6 +318,53 @@ const stories = await howone.entities.Story.list({ limit: 50, sort: 'title' })
 
 ---
 
+## Public Reads
+
+Use public reads for public lists and scoped public pages.
+
+```ts
+const articles = await howone.public.entities.Article.query({
+  published: true,
+  category: 'ai',
+  page: { number: 1, size: 20 },
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
+For `access.public.read = "scoped"`, pass every required scope:
+
+```ts
+const profile = await howone.public.entities.QrProfile.queryScoped({
+  ownerId: ownerSharedUserId,
+  slug: 'wechat',
+  active: true,
+  limit: 1,
+})
+```
+
+Public query fields must be present in `access.public.allowedFilters`, and public sort
+fields must be present in `access.public.allowedSorts`. If a public query is rejected,
+fix the schema access contract instead of falling back to authenticated APIs.
+
+---
+
+## Public Writes
+
+Only generate public writes when `access.public.create` / `access.public.update` allows
+them. Public create must include `created_by_user_id` unless the schema defines a
+different required owner scope.
+
+```ts
+await howone.public.entities.ContactMessage.create({
+  created_by_user_id: projectUserId,
+  name: 'Ada',
+  email: 'ada@example.com',
+  message: 'Please contact me',
+})
+```
+
+---
+
 ## Bulk Create
 
 ```ts

package/templates/vite/.howone/skills/howone-sdk/references/04-auth.md

@@ -45,10 +45,13 @@ import { HowOneAuthError } from '@howone/sdk'
 import howone from '@/lib/sdk'
 
 type UserProfile = {
-  id: string
+  id: string       // backend owner id; same as userId when JWT has userId
+  userId?: string  // authenticated backend user id when present in JWT
+  puid?: string    // public UUID; do not use as public ownerId scope
   email?: string
   name?: string
   avatarUrl?: string
+  appId?: string
   roles?: string[]
   metadata?: Record<string, unknown>
 }
@@ -66,6 +69,18 @@ const user = await howone.session.user()
 const user = await howone.me({ refresh: true })
 ```
 
+### Identity fields
+
+HowOne JWTs may contain both `userId` and `puid`. The SDK preserves both:
+
+- `user.id` / `user.userId` identifies the authenticated backend user.
+- `user.puid` is the public UUID and should not be used for entity owner filters.
+- `query.mine()` requires auth and lets the backend derive ownership from the JWT.
+
+For public share URLs that need scoped owner data, use `howone.public.entities.*`
+and pass the schema-required public scope, usually the shared owner id stored on a record.
+Do not pass `puid` as `ownerId`.
+
 ### Pattern: guard a page
 
 ```tsx

package/templates/vite/.howone/skills/howone-sdk/references/06-react-integration.md

@@ -31,17 +31,20 @@ import {
 
 Wrap your entire app. Provides auth, theme, and toast context to all children.
 
+`HowOneProvider` reads SDK environment and project defaults from `createClient`. Configure
+`projectId` and `env` once in `src/lib/sdk.ts`; do not pass a separate env to the provider.
+
 ```tsx
 // main.tsx or app/layout.tsx
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { HowOneProvider } from '@howone/sdk/react'
+import './lib/sdk'
 import App from './App'
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <HowOneProvider
-      projectId={import.meta.env.VITE_HOWONE_PROJECT_ID}
       auth="required"
       brand="visible"
       theme="system"
@@ -62,7 +65,7 @@ type HowOneBrandMode = 'visible' | 'hidden'
 interface HowOneProviderProps {
   children: React.ReactNode
 
-  // Project configuration (optional if createClient already set it)
+  // Optional override. Prefer configuring projectId once in createClient.
   projectId?: string
 
   // Auth behaviour
@@ -115,10 +118,13 @@ Access auth state inside any component wrapped by `HowOneProvider`.
 ```ts
 type HowoneContextValue = {
   user: {
-    id: string
+    id: string       // backend owner id; same as userId when JWT has userId
+    userId?: string  // authenticated backend user id when present in JWT
+    puid?: string    // public UUID; do not use as public ownerId scope
     email: string
     name: string
     avatar: string
+    appId?: string
   } | null
   token: string | null
   isAuthenticated: boolean
@@ -323,6 +329,7 @@ import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { HowOneProvider } from '@howone/sdk/react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import './lib/sdk'
 import App from './App'
 
 const queryClient = new QueryClient()
@@ -330,7 +337,6 @@ const queryClient = new QueryClient()
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <HowOneProvider
-      projectId={import.meta.env.VITE_HOWONE_PROJECT_ID}
       auth="required"
       theme="system"
       brand="visible"

package/templates/vite/.howone/skills/howone-sdk/references/08-manifest-codegen.md

@@ -62,9 +62,41 @@ Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. T
 | `array` (items: object) | `Record<string, unknown>[]` or inline type |
 | `object` | `Record<string, unknown>` |
 | `enum` | `'value1' \| 'value2' \| ...` |
+| `["string", "null"]` | `string \| null` |
 
-- Fields in `required: true` are non-optional in `Record` and `Create` types.
-- Fields in `required: false` (or absent from required list) get `?` in `Record` and are optional in `Create`.
+- Fields in `required: true` are non-optional in `Record` types.
+- In `Create` types, required fields are required only when they do not have `default` or `autoGenerate`.
+- Fields with `default`, `defaultValue`, or `autoGenerate` are optional in `Create`.
+- Nullable fields include `null`.
+- System response fields are never generated into `Create` or `Update`.
+
+### Access-aware generated helpers
+
+Use the manifest `access` block to decide which namespace UI code should call:
+
+```ts
+export type ArticlePublicQuery = {
+  published?: boolean
+  category?: string
+  slug?: string
+  page?: { number?: number; size?: number }
+  orderBy?: { publishedAt?: 'asc' | 'desc'; updatedDate?: 'asc' | 'desc' }
+}
+
+const publicArticles = await howone.public.entities.Article.query({
+  published: true,
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
+Rules:
+
+- `access.authenticated.*` drives `howone.entities.*`.
+- `access.public.read = "list"` allows `howone.public.entities.Entity.query`.
+- `access.public.read = "scoped"` requires `queryScoped` / `query.scoped` and all `requiredScopes`.
+- Public query types must include only `allowedFilters`, `allowedSorts`, `page`, `limit`, `search`, `include`, and `exactCount`.
+- Public create/update types should only be emitted when `access.public.create/update` is not `"none"`.
+- Public create must include `created_by_user_id` when the schema requires public owner assignment.
 
 ### Generated TypeScript from the example manifest
 
@@ -335,7 +367,9 @@ Before finalising generated code, verify:
 
 - [ ] Every entity from `.howone/database/manifest.json` has a `Record`, `Create`, and `Update` type
 - [ ] `Create` types are defined **explicitly** (not via `Omit`)
-- [ ] Optional fields match `required: false` in the manifest
+- [ ] Create optionality accounts for `required`, `default`, `defaultValue`, `autoGenerate`, and nullable types
+- [ ] System fields are not present in create/update input types
+- [ ] Public query/write types are generated only from `access.public.allowedFilters`, `allowedSorts`, `requiredScopes`, and write permissions
 - [ ] Every AI action from `.howone/ai/manifest.json` has an `inputSchema` zod object
 - [ ] Required input fields are not `.optional()` in zod
 - [ ] AI action names match the manifest `id` exactly (case-sensitive)

package/templates/vite/AGENTS.md

@@ -1,53 +1,45 @@
 # AGENTS.md
 
-This file defines project-specific instructions for coding agents.
+This is a standard HowOne Vite app.
 
-Read this file once when entering the project.
-Follow it during implementation.
-Do not repeatedly reread it unless it changes or the current task requires checking project rules again.
+Read this file once when entering the project, follow it during implementation, and do not reread it unless it changes or the current task genuinely requires checking project rules again.
 
-## Multi-turn Policy
+## Project Defaults
 
-After reading this file, maintain a concise project policy summary for the active workspace session.
-Use that summary across turns instead of rereading this file or relying on old chat history.
+- Package manager: `bun`
+- Common commands: `bun run dev`, `bun run typecheck`, `bun run build`
+- The scaffold normally installs dependencies during `howone init app`. If `node_modules` is missing, run `bun install` before validation instead of treating missing binaries as code failures.
+- Default stack: React, Vite, TypeScript, Tailwind CSS, shadcn/ui-style components, `@howone/sdk`
 
-The project policy summary should stay short and include only durable rules:
+## Source of Truth
 
-- package manager and common commands
-- trusted libraries and framework assumptions
-- context-loading rules
-- validation rules
-- project-specific constraints
+Use project-local sources in this order:
 
-Do not store transient command output, temporary reasoning, full file contents, or step-by-step logs in the project policy.
+1. Synced HowOne manifests under `.howone/`
+2. Generated SDK bindings such as `src/lib/sdk.ts`
+3. The smallest directly relevant app files
+4. Package/config metadata
+5. Dependency source only when a concrete mismatch or missing detail remains
 
-Maintain a separate short task state summary while implementing a user request:
+Do not guess generated entity names, AI action names, schemas, workflow IDs, or auth behavior when a synced manifest exists.
 
-- current goal
-- current phase: explore, implement, validate, fix, or done
-- files already read
-- files changed
-- last validation command and result
-- known blockers or open questions
+## Context Discipline
 
-Use task state to avoid repeating exploration or rereading unchanged files. Reset or replace it when the user starts a new unrelated task.
-
-Do not reread this file unless:
-
-- this file changed
-- the project policy summary is unavailable
-- the task enters a nested project with its own `AGENTS.md`
-- validation errors suggest a project rule was missed
+Start with the smallest useful context:
 
-## Library Trust Policy
+1. Read the smallest file that directly controls the requested behavior.
+2. Prefer manifests, config, and public library APIs before local library internals.
+3. Expand only when implementation, validation, or a concrete ambiguity requires it.
 
-For common public libraries already known to modern coding models, prefer model knowledge and package metadata over reading local source files.
+For ordinary page or feature work:
 
-This project may include generated or vendored library-style files, such as shadcn/ui components under `src/components/ui/*`.
+- Start with the relevant route, page, feature component, or entry file.
+- Read additional local files only when they directly control the behavior being changed or resolve a specific uncertainty.
+- If a manifest, config file, or validation error answers the question, prefer that over widening the file search.
 
-Do not inspect these files during ordinary feature work just to confirm standard APIs.
+## Trusted Libraries
 
-Examples of trusted public libraries:
+Treat common public libraries as known dependencies during ordinary feature work:
 
 - React
 - Vite
@@ -59,39 +51,38 @@ Examples of trusted public libraries:
 - clsx
 - class-variance-authority
 
-When implementing ordinary usage of these libraries:
+Do not inspect `src/components/ui/*` or other library-style source files just to rediscover standard APIs.
 
-1. Use standard public APIs first.
-2. Read `package.json`, `components.json`, `tsconfig.json`, or alias config only when needed.
-3. Implement the feature.
-4. Run build/typecheck.
-5. Inspect the smallest relevant local file only if validation fails or the API is genuinely unclear.
+Using or importing a standard UI primitive is not by itself a reason to read its local source. For ordinary feature work, use the public component name and existing import path first.
 
-Only read local component or library-style source files when:
+Read local component or library-style source only when:
 
-- build/typecheck fails
-- imports cannot be resolved from `package.json`, `tsconfig.json`, or `components.json`
-- the component API is unclear
-- the task requires modifying the component implementation
-- the project has custom wrappers, custom variants, or unusual exports
+- validation fails
+- imports cannot be resolved from package/config metadata
+- the API is genuinely unclear
+- the task edits that component
+- the project has custom wrappers, variants, or unusual exports
 - the user explicitly asks to follow local component conventions
 
 Prefer failure-driven inspection over speculative context loading.
 
-## Context Budget Policy
-
-Start with the smallest useful context:
+## HowOne Runtime and Auth
 
-1. Identify the app root and relevant scripts.
-2. Read the smallest file that directly controls the requested behavior.
-3. Prefer package metadata, config files, and public API usage before local library internals.
-4. Expand to additional files only when implementation, validation, or ambiguity requires it.
+- Use synced HowOne manifests plus `src/lib/sdk.ts` as the source of truth for generated entity and AI bindings.
+- For SDK work, use the `howone-sdk` skill before relying on package internals.
+- 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
+- For private authenticated features, use the app-level HowOne auth flow instead of inventing unauthenticated fallback data paths.
+- Do not pass owner fields such as `created_by_id`, `created_by_user_id`, `ownerId`, or `puid` into authenticated entity queries or writes.
 
-Avoid broad project scans unless the user asks for a repository-wide change or the relevant files are genuinely unknown.
+## Validation
 
-## Validation Policy
+After meaningful code changes:
 
-After meaningful code changes, run the narrowest relevant validation command available in this project.
-Prefer build or typecheck before deeper investigation into library internals.
+1. If dependencies are unavailable, run `bun install` first.
+2. Run the narrowest relevant validation, usually `bun run typecheck`.
+3. Run `bun run build` when the change affects app wiring, SDK integration, routes, or production bundling.
+4. If validation fails, inspect the smallest failing surface before widening context.
 
-If validation fails, inspect the smallest file or error location needed to fix the failure.
+Work is complete when the requested change is implemented, relevant validation has been run, and any remaining blocker is reported clearly.

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.11",
+    "@howone/sdk": "2.0.0-beta.16",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",