howone 0.2.3 → 0.2.6

package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md

@@ -1,41 +1,27 @@
-# AI Manifest Handoff (App SDK)
+# AI Manifest Handoff
 
-Use this reference after AI capability artifacts have been synced and app code must call the
-workflow through `@howone/sdk`.
+Use this track after `sync_ai_artifacts` and external workflow submission. It is the short handoff
+from `.howone/ai/manifest.json` to `src/lib/sdk.ts`; use `07-ai-action-calls.md` for execution
+semantics and `10-workflow-execute-sse.md` for wire details.
 
-This file answers: **how does `.howone/ai/manifest.json` become `src/lib/sdk.ts`, and how should UI
-call it?**
+## Handoff protocol
 
-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`.
+1. Read the current manifest, not a cached tool response.
+2. Confirm every action has an exact UUID `workflowId`.
+3. Generate Zod input/output schemas from the manifest.
+4. Bind with `defineAiAction` and compose with `withAiActions`.
+5. Run `node .howone/skills/howone/scripts/verify-project.mjs`, typecheck, and build.
 
-## Binding Source
+Workflow create/update can rotate the config UUID. After every successful external workflow
+operation, sync and re-read the manifest before deciding whether the app binding changed.
 
-Generate `src/lib/sdk.ts` from `.howone/ai/manifest.json`. Do not write AI bindings from memory,
-from the original prompt, or from the workflow service response.
+There is no action-name fallback. A missing UUID is a module initialization error, not a server
+request that can be repaired later.
 
-For each manifest capability/action:
-
-1. Read stable action name/ID.
-2. Read `workflowId`.
-3. Read `inputSchema`.
-4. Read `outputSchema`.
-5. Generate Zod input and output schemas.
-6. Bind with `defineAiAction(name, { workflowId, inputSchema, outputSchema })`.
-7. Compose with `withAiActions(client, ai)`.
-
-`workflowId` is mandatory. Without it, the SDK falls back to the action name as the execution URL
-segment, and the workflow service will reject it because the segment is not a UUID.
-
-## Generated Binding Example
+## Example
 
 ```ts
-import {
-  createClient,
-  defineAiAction,
-  defineAiActions,
-  withAiActions,
-} from '@howone/sdk'
+import { createClient, defineAiAction, defineAiActions, withAiActions } from '@howone/sdk'
 import { z } from 'zod'
 
 const client = createClient({
@@ -43,22 +29,14 @@ const client = createClient({
   env: import.meta.env.VITE_HOWONE_ENV,
 })
 
-export const summarizeDocumentInputSchema = z.object({
-  document_url: z.string().url(),
-  summary_length: z.string().optional(),
-})
-export type SummarizeDocumentInput = z.infer<typeof summarizeDocumentInputSchema>
+const inputSchema = z.object({ documentUrl: z.string().url() })
+const outputSchema = z.object({ summary: z.string() })
 
-export const summarizeDocumentOutputSchema = z.object({
-  summary: z.string(),
-})
-export type SummarizeDocumentOutput = z.infer<typeof summarizeDocumentOutputSchema>
-
-export const ai = defineAiActions({
+const ai = defineAiActions({
   summarizeDocument: defineAiAction('summarizeDocument', {
     workflowId: '550e8400-e29b-41d4-a716-446655440000',
-    inputSchema: summarizeDocumentInputSchema,
-    outputSchema: summarizeDocumentOutputSchema,
+    inputSchema,
+    outputSchema,
   }),
 })
 
@@ -66,172 +44,47 @@ const howone = withAiActions(client, ai)
 export default howone
 ```
 
-## JSON Schema To Zod
+The UUID above is illustrative only. Copy the real value from the current manifest.
+
+## Schema conversion rules
 
 | JSON Schema | Zod |
 |---|---|
-| `string` | `z.string()` |
-| `string` + `format: "uri"` | `z.string().url()` |
-| `number` | `z.number()` |
-| `integer` | `z.number().int()` |
-| `boolean` | `z.boolean()` |
-| `array` of strings | `z.array(z.string())` |
-| `array` of objects | `z.array(z.object({ ... }))` |
-| `object` | `z.object({ ... })` |
-| string enum | `z.enum([...])` |
-| field not in `required` | `.optional()` |
-| nullable | `.nullable()` |
-
-Rules:
-
-- Required manifest fields must stay required in Zod.
-- Do not add `.passthrough()` to hide execution envelope problems.
-- Do not make outputs optional to silence validation failures.
-- If the workflow returns a different shape, fix the workflow/capability contract.
-
-## Calling Actions
-
-For typed one-shot actions:
-
-```ts
-const output = await howone.ai.summarizeDocument.run({
-  document_url,
-  summary_length: 'short',
-})
-
-setSummary(output.summary)
-```
-
-When `outputSchema` exists, `.run()` returns the validated `finalResult` payload directly.
-
-Do not read:
-
-```ts
-result.finalResult.summary
-result.data.summary
-result.raw.finalResult
-```
-
-Those are execution-envelope paths, not the typed SDK action contract.
-
-## Streaming And Events
-
-Use `.stream()` when UI needs live output or cancellation:
-
-```ts
-const session = howone.ai.generateStory.stream(input, {
-  onMessageChunk: (line) => appendLog(line),
-  onProgress: (percent, line) => {
-    if (line?.startsWith('[DISPLAY]')) setStatus(line.replace('[DISPLAY]', '').trim())
-    if (percent === 100) setProgress(100)
-  },
-  onCreditInsufficient: (event) => showCreditError(event.message),
-  onRunError: (event) => showExecutionError(event.message),
-  onError: (error) => setError(error.message),
-  onComplete: (result) => setRawResult(result),
-})
-
-cancelButton.onclick = () => session.cancel()
-const final = await session.result
-```
-
-Use `.events()` when code wants an async iterable:
-
-```ts
-for await (const event of howone.ai.generateStory.events(input)) {
-  if (event.type === 'progress') {
-    appendLog(String(event.message))
-  }
-  if (event.type === 'run_complete') {
-    setFinalResult(event.message)
-  }
-  if (event.type === 'credit_insufficient') {
-    showCreditError(String(event.message))
-  }
-  if (event.type === 'run_error') {
-    showExecutionError(String(event.message))
-  }
-}
-```
-
-## UI State
-
-The SDK returns data and exposes callbacks. The app owns all visible UI.
-
-Recommended states:
-
-```ts
-type AiUiState<T> =
-  | { status: 'idle' }
-  | { status: 'running'; progress?: number }
-  | { status: 'succeeded'; output: T }
-  | { status: 'failed'; message: string }
-  | { status: 'cancelled' }
-```
+| string | `z.string()` |
+| string URI | `z.string().url()` |
+| number/integer | `z.number()` / `z.number().int()` |
+| boolean | `z.boolean()` |
+| array | `z.array(item)` |
+| object | `z.object({ ... })` |
+| enum | `z.enum([...])` |
+| nullable | `z.nullable(...)` |
+| not required | `.optional()` |
 
-Do not add or import SDK toast APIs. Do not show SDK-owned overlays.
+Do not make required fields optional and do not use `.passthrough()` to conceal a workflow result
+shape mismatch. Typed `.run()` returns the validated final result directly.
 
-## Persistence Handoff
-
-If AI output should survive refresh, use entity persistence after the action returns.
-
-For history-style products, prefer `runAiActionAndPersist()`:
+## Result handoff
 
 ```ts
-const result = await runAiActionAndPersist({
-  entity: howone.entities.Generation,
-  input: { prompt },
-  createPending: (input) => ({
-    prompt: input.prompt,
-    status: 'pending',
-    requestedAt: new Date().toISOString(),
-  }),
-  run: (input) => howone.ai.generateImage.run(input),
-  mapCompleted: ({ output }) => ({
-    status: 'completed',
-    resultUrl: output.generated_image_url,
-    completedAt: new Date().toISOString(),
-  }),
-  mapFailed: ({ error }) => ({
-    status: 'failed',
-    errorMessage: error instanceof Error ? error.message : 'Generation failed',
-  }),
-})
-```
-
-For simple save-after-success:
-
-```ts
-const output = await howone.ai.summarizeDocument.run(input)
+const output = await howone.ai.summarizeDocument.run({ documentUrl })
 await howone.entities.DocumentSummary.create({
-  documentUrl: input.document_url,
+  documentUrl,
   summary: output.summary,
   status: 'completed',
 })
 ```
 
-Do not ask the workflow to write records. Do not pass owner fields for authenticated own entities.
-
-## Workflow Edit Handoff
-
-When changing external workflow behavior later:
-
-1. If schema changes, update AI capability contract first and sync manifest.
-2. Submit update through `external-ai-capability` with `updates: [{ capabilityName, updatePrompt }]`.
-3. Re-read `.howone/ai/manifest.json`; update may rotate `workflowId` to a fresh config UUID.
-4. Regenerate SDK bindings whenever the manifest `workflowId`, input schema, or output schema changed.
-5. Behavior-only updates still require checking the manifest before deciding SDK is unchanged.
+For history, use pending-first `runAiActionAndPersist`. The workflow does not perform database CRUD;
+the app persists through generated entity bindings.
 
-The SDK does not use old `workflowConfigID` status values. It binds to the current manifest
-`workflowId`, which is the EAX config id used in execution URLs.
+For streaming, use `onMessageChunk`, await `session.result`, and catch terminal workflow errors.
+For events, a terminal error event is yielded before the iterator rejects.
 
-## Handoff Checklist
+## Final checklist
 
-- `.howone/ai/manifest.json` exists and is current.
-- Each action has `workflowId`.
-- Zod input/output schemas match manifest required fields.
-- `defineAiAction` uses action name + exact workflow UUID.
-- UI uses returned typed output, not raw execution envelope.
-- Streaming session is cancellable when UI exposes cancel.
-- Persistence goes through `howone.entities.*`.
-- Visible status/error UI is app-owned.
+- [ ] Current AI manifest was read after the last sync.
+- [ ] Action IDs and UUIDs match exactly.
+- [ ] Zod requiredness/enums match the manifest.
+- [ ] No `aiUrl`, `aiBaseUrl`, or raw EAX URL was added.
+- [ ] App uses `HowOneProvider client={howone}`.
+- [ ] Verifier, typecheck, and build pass.

package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md

@@ -86,7 +86,7 @@ Use callbacks instead:
 
 ```tsx
 <HowOneProvider
-  auth="required"
+  client={howone}
   brand="visible"
   onAuthRedirect={({ mode, returnUrl }) => {
     setAuthUi({ redirecting: true, mode, returnUrl })
@@ -102,8 +102,8 @@ Use callbacks instead:
 Hide the logo only when explicitly requested:
 
 ```tsx
-<HowOneProvider brand="hidden" />
-<HowOneProvider showBrandButton={false} />
+<HowOneProvider client={howone} brand="hidden" />
+<HowOneProvider client={howone} showBrandButton={false} />
 ```
 
 ## UI Feedback Rule
@@ -132,7 +132,7 @@ For streaming workflows, use callbacks/events:
 const session = howone.ai.generateImage.stream(
   { prompt },
   {
-    onStreamContent: (delta) => appendLog(delta),
+    onMessageChunk: (delta) => appendLog(delta),
     onProgress: (progress) => setProgress(progress),
     onError: (error) => setStatus({ type: 'error', message: error.message }),
     onComplete: (result) => setResult(result.finalResult),

package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md

@@ -1,52 +1,40 @@
 # Workflow Execute SSE
 
-Use this reference for `@howone/sdk` AI action streaming and raw workflow execution calls.
+Use this reference when an app needs live workflow progress, cancellation, or raw event iteration.
+For ordinary AI actions, start with `07-ai-action-calls.md` and use the typed action methods.
 
-## Endpoint Contract
+## Environment and endpoint
 
-The SDK uses the current workflow execute SSE endpoint:
+The SDK chooses the EAX base from `createClient({ env })`:
 
-| Method | Path |
+| `env` | EAX base |
 |---|---|
-| `POST` | `/workflow/execute/{project_short_id}/{config_id}` |
+| `local` | `https://eax-backend-orchestrator-dev.fly.dev` |
+| `dev` | `https://eax-backend-orchestrator-dev.fly.dev` |
+| `prod` | `https://eax-backend-orchestrator-prod.fly.dev` |
 
-The request body is:
+Do not construct this URL in app code or override it with `aiUrl`. A workflow action calls:
 
-```json
-{
-  "inputs": {},
-  "priority": "normal"
-}
+```text
+POST {eaxBase}/workflow/execute/{projectId}/{workflowId}
 ```
 
-`priority` is optional. All requests require `Authorization: Bearer <JWT>`.
-
-The successful HTTP response includes:
-
-| Header | Meaning |
-|---|---|
-| `Content-Type: text/event-stream` | Streaming response |
-| `X-Run-Id` | Execution task id for status/cancel follow-up |
-
-Do not use or generate code for old endpoints such as
-`/workflow/{appId}/{workflowId}/execute_sse`.
+The request body is `{ inputs: {}, priority?: 'low' | 'normal' | 'high' }` and carries the current
+client token as `Authorization: Bearer ...`.
 
-## Wire Format
+## Wire protocol
 
-Frames contain only a `data:` line and a blank line:
+Frames are JSON `data:` lines separated by a blank line. The JSON envelope owns the ID and event
+name; there are no separate legacy SSE `id:` or `event:` lines:
 
 ```text
-data: {"id":"evt_8ae6d6e8a4ea","event":"run_start","message":"execution with sse is started"}
+data: {"id":"evt_1","event":"run_start","message":"execution with sse is started"}
 
-data: {"id":"evt_241ff985450b","event":"progress","message":"[DISPLAY] Executing node: Extract"}
+data: {"id":"evt_2","event":"progress","message":"[DISPLAY] Executing node: Extract"}
 
-data: {"id":"evt_f3a1b2c3d4e5","event":"run_complete","message":{"video_url":"https://..."}}
+data: {"id":"evt_3","event":"run_complete","message":{"imageUrl":"https://..."}}
 ```
 
-There are no separate SSE `event:` or `id:` lines. The JSON envelope owns those fields.
-
-## Envelope
-
 ```ts
 type WorkflowSseEnvelope = {
   id: string
@@ -55,51 +43,96 @@ type WorkflowSseEnvelope = {
 }
 ```
 
-Event meanings:
-
-| Event | Message | Meaning |
-|---|---|---|
-| `run_start` | string | Stream opened and execution started. |
-| `progress` | string | One worker log line. `[DISPLAY]` lines are intended for UI. |
-| `run_complete` | object | Final workflow-specific output. SDK maps this to `AiResult.finalResult`. |
-| `run_error` | string | Workflow failed. |
-| `credit_insufficient` | string | Billing/credit block. |
-
 The terminal event is exactly one of `run_complete`, `run_error`, or `credit_insufficient`.
-There is no `stream_end` event.
-
-## SDK Mapping
-
-`howone.ai.run(configId, inputs)` and typed action `.run()` call the endpoint above.
+There is no `stream_end`, `node_start`, `tool_call_end`, or `ai_message_chunk` event in this
+workflow endpoint.
 
-`AiResult` maps the stream as:
+## SDK mapping
 
 ```ts
 type AiResult = {
   success: boolean
-  runId?: string
+  runId?: string // X-Run-Id response header
   outcome: 'success' | 'credit_insufficient' | 'run_error' | null
   finalResult: Record<string, unknown> | null
   progressLogs: string[]
+  stateData: Record<string, unknown> // deprecated; always empty for this protocol
+  nodeExecutions: unknown[]           // deprecated; always empty
+  toolExecutions: unknown[]           // deprecated; always empty
+  totalDuration: number
   errors: string[]
   events: AiEvent[]
 }
 ```
 
-For typed actions with an `outputSchema`, `.run()` returns the validated `run_complete.message`
-object directly.
+`run_complete.message` becomes `finalResult`. `progress.message` lines append to `progressLogs`.
+`run_error` and `credit_insufficient` append errors and cause `run()`/`stream.result` to reject with
+`WorkflowExecutionError`; the `events()` iterator yields the terminal event before rejecting.
+
+## UI pattern
+
+```tsx
+function WorkflowProgress({ input }: { input: GenerateInput }) {
+  const [logs, setLogs] = useState<string[]>([])
+  const [error, setError] = useState<string | null>(null)
+
+  async function run() {
+    const controller = new AbortController()
+    try {
+      const result = await howone.ai.generate.run(input, {
+        signal: controller.signal,
+        onMessageChunk: (line) => setLogs((current) => [...current, line]),
+      })
+      console.log(result)
+    } catch (value) {
+      setError(value instanceof Error ? value.message : String(value))
+    }
+  }
+
+  return <button onClick={() => void run()}>Run workflow</button>
+}
+```
+
+For a cancel button, keep the controller/session in a ref and call `abort()` or `session.cancel()`.
+Treat abort as a user action in UI; do not report it as an EAX `run_error`.
 
-## Callback Rules
+## Callback rules
 
-- `onRunStart(event)` receives the `run_start` envelope.
-- `onMessageChunk(text, event)` receives each `progress.message` line.
-- `onProgress(0, message)` receives each progress line; `onProgress(100)` fires on success.
-- `onRunComplete(event, result)` receives `event.message` as the final object.
-- `onRunError(event)` receives `event.message` as the error string.
-- `onCreditInsufficient(event)` receives `event.message` as the credit error string.
-- `onEvent(event, 'workflow')` fires for every parsed envelope.
+- `onEvent(event, 'workflow')` fires for each parsed envelope.
+- `onRunStart` fires for `run_start`.
+- `onMessageChunk(text, event)` fires for each non-empty progress line.
+- `onProgress(0, message)` is a compatibility callback for progress lines; `onProgress(100)` fires
+  on successful completion.
+- `onRunComplete` receives the final object.
+- `onRunError` and `onCreditInsufficient` receive terminal messages.
+- `onComplete` receives the assembled result before a terminal failure is rejected.
+- `onError` receives transport and terminal errors.
 
-Do not write UI code that expects `event.payload.result`, `event.payload.details.reason`,
-`node_start`, `tool_call_end`, `state_update`, or `ai_message_chunk`. Those belong to an old
-multi-channel protocol and are not part of the current workflow execute SSE contract.
+Callbacks are not a substitute for awaiting `run()` or `session.result`; always handle the promise.
+The SDK retains at most 1,000 events and 500 progress lines by default while still invoking callbacks
+for every event. Configure the bounds for a diagnostic screen rather than retaining unbounded logs.
 
+## Raw event iteration
+
+```ts
+try {
+  for await (const event of howone.ai.generate.events(input)) {
+    renderEvent(event)
+  }
+} catch (error) {
+  renderFailure(error)
+}
+```
+
+On a terminal failure, consumers see the `run_error` or `credit_insufficient` event before the
+iterator rejects. Breaking the loop cancels the underlying reader.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Calling the old `/workflow/{appId}/{id}/execute_sse` path | Use the typed SDK action. |
+| Adding `/api` to EAX URL | EAX base is not the REST base; app code should not build it. |
+| Using `onStreamChunk`/`onTextChunk` | Use `onMessageChunk`. |
+| Treating `run_error` as a successful result | Catch `WorkflowExecutionError` and inspect `outcome`. |
+| Parsing `event.payload.result` | Read `event.message`; `run_complete` message is the final object. |

package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md

@@ -189,7 +189,7 @@ Schema:
       "create": "scoped",
       "update": "none",
       "delete": "none",
-      "requiredScopes": ["created_by_user_id"],
+      "requiredScopes": ["submissionKey"],
       "allowedFilters": [],
       "allowedSorts": [],
       "defaultLimit": 1,
@@ -203,7 +203,7 @@ Frontend:
 
 ```ts
 await howone.public.entities.Feedback.create({
-  created_by_user_id: projectUserId,
+  submissionKey,
   message,
   rating,
 })
@@ -211,7 +211,8 @@ await howone.public.entities.Feedback.create({
 
 Rules:
 
-- Public create needs a clear `created_by_user_id` source when backend requires ownership mapping.
+- Public create must use the declared public scope/business fields. Never pass ownership/system
+  fields such as `created_by_user_id`; the SDK rejects them and the backend derives ownership/scope.
 - Do not expose public read unless needed.
 - Add anti-abuse UX/server constraints outside the dynamic schema when needed.
 - Never persist UI-only fields from form components.

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

@@ -13,6 +13,24 @@ HowOne builds generated full-stack AI apps. Platform contracts are separate from
 
 Load only the track needed for the user's request. Do not read SDK files while designing backend or AI contracts unless the task has reached manifest-to-code implementation.
 
+## Version Evidence (Mastra-style)
+
+Before writing app SDK code, establish this evidence chain:
+
+```text
+synced project manifests
+→ app package.json SDK range
+→ installed @howone/sdk version
+→ installed dist/*.d.ts and runtime exports
+→ this Skill's matching recipe
+→ remote docs only as supplemental context
+```
+
+Read `references/version-evidence.md` and run
+`node .howone/skills/howone/scripts/verify-project.mjs` from the app root. If the requested and
+installed SDK versions disagree, install dependencies before coding. Never solve a version mismatch
+with `any`, guessed signatures, or copied latest documentation.
+
 ## Trigger Preconditions
 
 Use this skill before work when any condition is true:
@@ -100,7 +118,8 @@ AI contract:
 
 ```text
 get_current_ai_capabilities -> apply_capability_patch -> sync_ai_artifacts -> external-ai-capability
--> wait for terminal result -> sync_ai_artifacts -> read .howone/ai/manifest.json
+-> continue independent app implementation (never end merely to wait)
+-> terminal result -> sync_ai_artifacts -> read .howone/ai/manifest.json
 ```
 
 No contract dry-run step. Normal generation applies one well-formed patch directly. For destructive,
@@ -110,10 +129,14 @@ approved patch.
 SDK/code:
 
 ```text
-read synced manifests -> choose auth posture -> update src/lib/sdk.ts -> install HowOneProvider
--> implement UI calls using src/lib/sdk.ts imports -> validate auth and runtime wiring
+read version evidence -> read synced manifests -> choose auth posture -> update src/lib/sdk.ts
+-> install HowOneProvider (client={howone}) -> implement UI calls using generated bindings
+-> run project verifier -> typecheck/build
 ```
 
+For fragile operations, prefer the deterministic verifier and the operation recipes over retyping
+transport details in an app. Run the verifier again after manifest or dependency changes.
+
 ## App Runtime Activation Gate
 
 Classify runtime activation before editing the application shell:
@@ -125,13 +148,13 @@ Classify runtime activation before editing the application shell:
   one module-level client in `src/lib/sdk.ts`, import it before Provider initialization, and wrap the
   application root in `HowOneProvider`.
 - HowOne AI, uploads, and `howone.entities.*` authenticated/private access require a real token path.
-  Default to hosted auth with `HowOneProvider auth="required"` unless the product explicitly requires
-  a custom or external login experience.
+  Use the default hosted client and pass the composed singleton to
+  `<HowOneProvider client={howone}>`; its required guard is inherited from `client.auth.guard`.
 - A custom HowOne login requires `createClient({ auth: 'custom', loginPath })`, a real OTP/OAuth flow
-  that writes the returned token through `howone.auth.setToken()`, and `HowOneProvider auth="none"`
-  with app-owned route guards. A login-looking screen without token acquisition is not completion.
+  that writes the returned token through `howone.auth.setToken()`, and a Provider receiving that
+  client. A login-looking screen without token acquisition is not completion.
 - An app that uses only manifest-approved `howone.public.entities.*` access may use
-  `HowOneProvider auth="optional"`; do not force login for a deliberately public experience.
+  `auth: 'none'`; the Provider inherits a non-required guard and must not force login.
 
 Do not delete the scaffold Provider while replacing `App.tsx` or `main.tsx` when the HowOne runtime
 is active. Before completion, verify the Provider still wraps the rendered app, the SDK module is
@@ -144,6 +167,7 @@ data, local-only persistence, or unauthenticated fallback behavior.
 - Backend fields/access/indexes: `{appRoot}/.howone/database/manifest.json` after sync.
 - AI names/workflow IDs/schemas: `{appRoot}/.howone/ai/manifest.json` after sync.
 - App runtime entry: `{appRoot}/src/lib/sdk.ts`.
+- Installed SDK typings/runtime: `{appRoot}/node_modules/@howone/sdk/dist/*` after package install.
 - Do not handwrite `.howone/` metadata.
 - Do not infer contract identifiers from prompts, memory, or dependency source.
 
@@ -196,6 +220,14 @@ Do not read unrelated capability references.
 | `04-app-sdk/11-entity-data-access-patterns.md` | App entity access calls from synced manifest |
 | `04-app-sdk/12-query-dsl-and-responses.md` | App query/filter/sort/pagination calls |
 
+### References and scripts
+
+| Resource | Use |
+|---|---|
+| `references/version-evidence.md` | Verify installed SDK version and declaration/runtime evidence before coding |
+| `references/common-errors.md` | Diagnose stale signatures, routing, auth, query, upload, and AI failures |
+| `scripts/verify-project.mjs` | Deterministically check project wiring and manifest workflow IDs |
+
 ## Hard Rules
 
 - Backend and AI design references must not include SDK implementation work.
@@ -206,6 +238,14 @@ Do not read unrelated capability references.
 - An active HowOne app runtime must include `src/lib/sdk.ts`, `HowOneProvider`, and the auth posture
   required by its AI/entity/upload access. Contract creation without usable authenticated app wiring
   is incomplete.
+- New app code must pass the composed singleton to `<HowOneProvider client={howone}>`; the Provider
+  derives its default route guard from `client.auth.guard`.
+- EAX workflow URLs are owned by `env`: `local/dev` use
+  `https://eax-backend-orchestrator-dev.fly.dev`, and `prod` uses
+  `https://eax-backend-orchestrator-prod.fly.dev`. Do not add `aiUrl`, `aiBaseUrl`, or a raw EAX URL.
+- `howone.raw.*` resolves to response data, not an AxiosResponse. Its REST base already includes
+  `/api`; app-owned paths must not repeat that prefix.
+- Use `@howone/sdk/devtools` for `ElementSelectorProvider`; keep core free of React imports.
 - AI workflows must not perform database CRUD; persistence is app code through entities.
 - Detailed capability references constrain workflow design; they do not replace synced manifests or
   define direct app SDK calls.