@agent-native/core 0.152.1 → 0.153.0

package/corpus/templates/dispatch/app/routes/settings.tsx

@@ -23,6 +23,7 @@ import { Link } from "react-router";
 import { messagesByLocale } from "@/i18n-data";
 
 import changelog from "../../CHANGELOG.md?raw";
+import { dispatchAccessDescriptor } from "../../shared/app-roles";
 
 export function meta() {
   return [{ title: messagesByLocale["en-US"].routeTitles.settings }];
@@ -30,7 +31,19 @@ export function meta() {
 
 export default function SettingsRoute() {
   const t = useT();
-  const agentSettingsTabs = useAgentSettingsTabs();
+  const agentSettingsTabs = useAgentSettingsTabs({
+    usageAppId: "dispatch",
+    usageViewAllHref: "/admin/metrics",
+    organizationContent: (
+      <div className="mx-auto w-full max-w-3xl">
+        <TeamPage
+          showTitle={false}
+          appRoles={dispatchAccessDescriptor}
+          createOrgDescription="Set up a team to share dispatch destinations and approvals with your colleagues."
+        />
+      </div>
+    ),
+  });
   const settingsTabs = [
     ...agentSettingsTabs,
     {
@@ -153,14 +166,6 @@ export default function SettingsRoute() {
           </SettingsGroup>
         </div>
       }
-      team={
-        <div className="mx-auto w-full max-w-3xl">
-          <TeamPage
-            showTitle={false}
-            createOrgDescription="Set up a team to share dispatch destinations and approvals with your colleagues."
-          />
-        </div>
-      }
       whatsNew={
         <div className="mx-auto w-full max-w-2xl">
           <ChangelogSettingsCard markdown={changelog} />

package/corpus/templates/dispatch/changelog/2026-08-12-search-and-pin-workspace-apps-from-the-app-catalog.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-12
+---
+
+Search and pin workspace apps from the app catalog

package/corpus/templates/dispatch/changelog/2026-08-12-workspace-integration-access-now-shows-exactly-which-apps-ca.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-12
+---
+
+Workspace integration access now shows exactly which apps can reuse each connection.

package/corpus/templates/dispatch/server/lib/app-roles.ts

@@ -0,0 +1,5 @@
+import { defineAppRoles } from "@agent-native/core/org";
+
+import { dispatchAccessDescriptor } from "../../shared/app-roles.js";
+
+export const dispatchAccess = defineAppRoles(dispatchAccessDescriptor);

package/corpus/templates/dispatch/shared/app-roles.ts

@@ -0,0 +1 @@
+export { dispatchAccessDescriptor } from "@agent-native/dispatch/shared/app-roles";

package/corpus/templates/factory/.agents/skills/adding-a-feature/SKILL.md

@@ -101,8 +101,9 @@ placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
 If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
-states, or formatting, read `internationalization` and update the app's i18n
-catalogs in the same change.
+states, or formatting, update the English source copy. Read the optional
+`internationalization` skill and update additional catalogs only when
+`translations.locales` in `agent-native.config.ts` includes them.
 
 For app-backed skills, declare skill visibility in the app-skill manifest:
 

package/corpus/templates/factory/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate actions, wiring navigation
+  state, or debugging agent context issues.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Core Patterns
+
+### 1. Navigation State (`navigation` key)
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent the semantic screen state: view, open IDs, active tab, and focused object.
+
+**UI side** — `useNavigationState`, an app-owned hook (not a framework import) that every template ships at `app/hooks/use-navigation-state.ts`. It is a thin wrapper around the framework primitive `useAgentRouteState`, handling both directions: writing `navigation` on route change and consuming the agent's `navigate` command.
+
+```tsx
+// app/hooks/use-navigation-state.ts
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are already exposed in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
+- Any durable selection — focused item, selected text range, active tab
+
+Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
+
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
+### 2. Current URL (`__url__` key)
+
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
+
+Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.
+
+### 3. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state,
+the current URL if filters matter, and selection state. It fetches the relevant
+data from existing domain actions, shared data helpers, or Drizzle queries, and
+returns a snapshot of what the user sees. Do not add REST wrappers just so
+`view-screen` can read app data. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const url = (await readAppState("__url__")) as {
+    searchParams?: Record<string, string>;
+  } | null;
+  const screen: Record<string, unknown> = { navigation };
+
+  if (url?.searchParams) {
+    screen.activeFilters = url.searchParams;
+  }
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const emails = await fetchEmailList(navigation.label);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
+
+### 4. The `navigate` Script
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
+
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
+
+Client code can use `useAgentRouteState`, `useSemanticNavigationState`, `setClientAppState`, `writeClientAppState`, `readClientAppState`, and `deleteClientAppState` from `@agent-native/core/client` instead of hand-written `fetch` calls. Pass `{ requestSource: TAB_ID }` on UI writes when pairing with `useDbSync({ ignoreSource: TAB_ID })`; pass `{ keepalive: true }` for short-lived writes such as selection cleanup during unload.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When processing sync events, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates these patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Reads `__url__` if URL query filters matter
+- Fetches email list matching current view/filter state
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+- For pure query-filter changes, use `set-search-params`
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include semantic route state in the `navigation` key (view, item IDs, active tab, focused row)
+- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
+- Update `view-screen` when adding new features — it should return data for every view
+- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
+- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How `useDbSync` delivers app-state changes to the UI
+- **actions** — How to create the `view-screen` and `navigate` actions
+- **storing-data** — Application-state is one of the core SQL stores

package/corpus/templates/factory/.agents/skills/frontend-design/SKILL.md

@@ -36,7 +36,7 @@ Before coding, decide:
   can wait until context or intent makes it relevant?
 - **Differentiation**: What makes this feel designed for this exact domain?
 
-Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
+Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, motion, empty states, loading states, focus states, and error states. Polish means removing copy, not writing more of it.
 
 ## Visual Direction Contract
 
@@ -54,80 +54,72 @@ before selecting its accent family. Shared behavior and semantic token names
 should stay consistent; palette, density, composition, type contrast, and
 shape language should not be identical by default.
 
-## High-Signal Minimalism And Progressive Disclosure
-
-Minimalism means fewer competing kinds of UI, not less useful information. Keep
-surfaces dense and scannable: reduce redundant prose, decorative containers,
-borders, badges, accent colors, and persistent controls before removing content
-that helps the user orient, compare, decide, or recover. The reference class is
-calm productivity software such as ChatGPT/Codex, Linear, and Vercel, not empty
-whitespace.
-
-### Product UX Philosophy
-
-Apply these principles as binding decision rules:
-
-- **Purpose over presence**: Every visible element must support orientation,
-  state comprehension, a decision, an action, or recovery. Before adding one,
-  name which; if it supports none or duplicates another element, remove or
-  defer it.
-- **Clarity over cleverness**: Use plain language, familiar patterns, explicit
-  hierarchy, and visible state. Do not make decoration or invented terminology
-  carry meaning. Preserve the labels, hit targets, focus states, and recovery
-  paths required for accessible use.
-- **Simple first, powerful on demand**: Keep the current task and state in the
-  default presentation. Put advanced, rare, diagnostic, and secondary work
-  behind contextual disclosure, menus, or Settings. Do not turn a discoverability
-  concern into permanent chrome, and do not hide information needed for the
-  current decision.
-- **Hierarchy over chrome**: Use typography, spacing, alignment, and restrained
-  emphasis to organize information. Treat prose, controls, borders, cards,
-  badges, and accent colors as a competition budget: reduce competing kinds of
-  elements before reducing useful information. When a surface has one clear
-  next decision, give it dominant emphasis and move secondary actions out of
-  the default path. Do not wrap every section in a card or add borders for
-  grouping alone; use spacing, alignment, typography, or dividers first. A
-  container must communicate grouping, state, or interaction.
-- **Coherence over novelty**: Reuse the product's primitives, interaction
-  patterns, and language. When given a screenshot or reference product, match
-  its underlying hierarchy, density, and behavior; do not copy decoration or
-  introduce a second visual language without a product reason.
-- **Quiet continuity**: Feedback must be immediate, contextual, and honest.
-  Preserve the user's place and layout, make loading, empty, and error states
-  understandable, and use motion only to explain a change.
-- **Respect repeated use**: Optimize for the hundredth use, not the first
-  impression. If a control repeats an explanation, occupies persistent space
-  for an occasional task, or turns routine work into ceremony, remove it or
-  move it to the contextual surface that owns it.
-
-### Progressive Disclosure And Information Timing
-
-Expose information and controls according to relevance, frequency, and
-consequence. Before coding, inventory the content and actions and assign them to
-the smallest useful visibility layer:
-
-1. **Orient and act**: location, current state, and context needed for the next
-   meaningful choice.
-2. **Support active work**: details and controls for the selected item or
-   current workflow.
-3. **Available on demand**: advanced settings, diagnostics, credentials,
-   metadata, destructive actions, documentation, and rare tools.
-
-Use a disclosure pattern that matches the task. Keep independent concerns easy
-to scan inside an expanded area instead of dumping every form, explanation,
-and secondary action into the first reveal. A collapsed row must retain its
-label and essential state; remove explanatory subtext unless it changes the
-next decision. For configuration with a known current state, show that state
-first and expose editing contextually instead of defaulting to a full form.
+## Default Surface Density
+
+This is the most repeated correction in this repo, tracked as `text-heavy-ui` in
+`node scripts/agent-friction-report.mjs`. Every item below has been asked for by
+name more than once, usually right after a previous surface was corrected for the
+same thing. So treat the list as the default shape you apply, not a tradeoff you
+weigh per surface. If the user wants one of these, they will ask.
+
+Density comes from data, not from prose. Linear, Vercel, and ChatGPT/Codex are
+dense — with rows, values, and state, and almost no explanatory sentences. That
+is the target: a surface full of information and nearly empty of narration. So
+"make it minimal" is never satisfied by removing data or by burying it behind
+extra clicks, and never blocked by deleting a sentence.
+
+Do not add, unless asked:
+
+- A page title that repeats the nav item or route the user just clicked, or a
+  breadcrumb on a page that already has a back arrow.
+- A description, subtitle, tagline, or eyebrow under any title — page, card,
+  panel, tab, dialog, settings group, or list row. A surface gets a title or a
+  description, never both.
+- A count, stat, or summary strip over content already on screen: "11 apps",
+  "25 results", "0 signals · 0 decisions · 0 runs".
+- An About, help, or "what this does" section in settings.
+- Helper text under each option in a chooser. The option label carries it.
+- A placeholder that restates its own label.
+
+The explanation goes in a tooltip, a `Manage` popover, a menu, or nowhere.
+Settings use one shape: a compact row with the label and its current state, one
+action on the right, and `Manage` revealing the form once something is
+configured. Do not spell every input out on the default surface.
+
+**Chrome is not content.** These rules govern strings you write into JSX. A
+`description` the user typed and the app stored is data — render it, and render
+nothing when it is empty. Never add a `|| "No description yet."` fallback; an
+empty field is empty, not an opening to explain the feature.
+
+### The Shape That Got Approved
+
+A multi-step connect flow the user accepted on 2026-08-12, after rejecting a
+dense dialog of the same content as "HORRIBLE ... overwhelming":
+
+- Full-screen takeover rather than a crowded modal. Generous empty space is fine.
+- One question per step as the heading ("Who should use this?"), at most one
+  short line under it, and nothing under the options.
+- Choices are single-line rows — icon plus label — with the common one
+  preselected, so the happy path is one click.
+- "Step 2 of 2" and a thin progress bar instead of every field at once.
+- Advanced and rare detail behind a labeled collapsed row ("Advanced details",
+  "App grants"): label only, no preview of the contents.
+- Current state shown rather than explained: "Dispatch can reuse this account".
+- Quiet Cancel on the left, primary action on the right.
+
+Use that same treatment for sibling flows. When the user points at another
+surface — "like forms", "like the integrations grid" — copy that surface's
+structure instead of inventing a second language for the same job.
+`templates/forms/` is the reference implementation: no page title, no
+breadcrumbs, no eyebrows, no card descriptions, and row subtext only where it
+renders a user-authored field.
 
 Before shipping, verify collapsed, expanded, loading, empty, error, and
 narrow-width states. The default state fails review when its first viewport
-contains multiple unrelated forms, repeated explanatory copy, documentation
-links, or controls for unrelated tasks. It also fails when useful information
-has been replaced with empty whitespace or extra clicks solely to look minimal.
-The default state passes when users can identify their location, current state,
-current task, and relevant next choice without reading documentation, while
-the useful information remains dense and scannable.
+carries explanatory paragraphs, several unrelated forms, or controls for another
+task. `guard:no-default-chrome` checks the structural half of this on lines your
+branch adds; it cannot see a sentence you wrote, so the list above is still
+yours to apply.
 
 ## Aesthetic Guidelines
 
@@ -212,8 +204,9 @@ the useful information remains dense and scannable.
 Before shipping a new app or a substantial redesign, review the surface as an
 operator would use it repeatedly:
 
-- Can users identify where they are, what state they are in, and what
-  meaningful choices or next steps are available?
+- Count the sentences in the first viewport. If any of them explains the UI
+  rather than reporting state, delete it. "Could a user identify where they are?"
+  is a question every surface passes; a sentence count is not.
 - Remove competing or redundant elements, then place optional inputs, provider
   choices, diagnostics, long explanations, and secondary actions where they
   remain discoverable without crowding the current task.
@@ -229,8 +222,8 @@ operator would use it repeatedly:
   consistent, but a repeated palette, hero composition, type pairing, and
   radius language without a product reason is visual drift, not consistency.
 - Check the result with realistic content at the target desktop width and a
-  narrow width. If it feels like documentation instead of a tool, reduce noise
-  or clarify the hierarchy.
+  narrow width. If it feels like documentation instead of a tool, subtract until
+  it does not — restyling it is not the fix.
 
 ## shadcn/ui Design Rules
 
@@ -241,7 +234,7 @@ operator would use it repeatedly:
 - Use `cn()` from the local utils alias for conditional classes.
 - Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
 - Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
-- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
+- Compose cards from `CardHeader`, `CardTitle`, `CardContent`, and `CardFooter`. Do not add `CardDescription`, and do not hand-roll a muted `<p>` under a `CardTitle` — a card gets a title or a description, never both.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
 - Page and section data loading uses layout-matching `Skeleton` geometry. Do
@@ -263,9 +256,9 @@ task without a clear product reason:
   preserve discoverability and reduce noise.
 - Full-width banners, persistent helper rows, decorative cards, or explanatory
   chrome for status that could be communicated more clearly with less weight.
-- Hiding essential meaning or operability behind progressive disclosure. Defer
-  complexity when it is contextual or infrequent, but preserve labels, focus,
-  hit targets, accessibility, and recovery paths.
+- Dropping a label, focus state, hit target, accessible name, or recovery path in
+  the name of minimalism. Defer complexity freely; never defer the ability to
+  operate the control.
 - UI cards nested inside other cards.
 - Text or icons that resize or shift fixed-format UI on hover/loading.
 

package/corpus/templates/factory/.agents/skills/portability/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: portability
+description: >-
+  How to keep template code database-agnostic and hosting-agnostic. Use when
+  defining schemas, writing raw SQL, creating server routes, or anything that
+  could leak a SQLite-only, Postgres-only, or Node-only assumption.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Portability
+
+## Rule
+
+**Never write code that only works on one database or one hosting platform.** Templates must run on portable SQL backends (SQLite, Postgres, D1, Turso/libSQL, Supabase, Neon, managed platform SQL environments when available) and any Nitro deploy target (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) without code changes.
+
+## Database Agnostic
+
+Use the dialect-agnostic schema helpers from `@agent-native/core/db/schema` for schemas and Drizzle's query builder for reads/writes:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  real,
+  now,
+  sql,
+} from "@agent-native/core/db/schema";
+
+export const meals = table("meals", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  calories: integer("calories").notNull(),
+  weight: real("weight"),
+  archived: integer("archived", { mode: "boolean" }).notNull().default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| Helper    | Purpose                                                                                   |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `table`   | Delegates to `pgTable` or `sqliteTable` based on dialect                                  |
+| `text`    | Works in both dialects, supports `{ enum: [...] }`                                        |
+| `integer` | `{ mode: "boolean" }` maps to Postgres `boolean` automatically                            |
+| `real`    | `real` on SQLite, `double precision` on Postgres                                          |
+| `now`     | Dialect-agnostic current timestamp — use with `.default(now())` on text timestamp columns |
+| `sql`     | Re-exported from `drizzle-orm` for raw SQL expressions                                    |
+
+**Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly in template code.** Always use `@agent-native/core/db/schema` instead.
+
+Use Drizzle's portable query DSL for app code:
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+
+const rows = await db
+  .select()
+  .from(meals)
+  .where(and(eq(meals.ownerEmail, userEmail), eq(meals.archived, false)))
+  .orderBy(desc(meals.createdAt));
+```
+
+Avoid `db.execute(...)`, `getDbExec()`, and handwritten SQL in actions, handlers, and stores when Drizzle can express the query. Raw SQL should be limited to additive migrations, health checks, carefully reviewed advanced queries, or one-off maintenance scripts. For timestamps in Drizzle schemas, use `.default(now())`; for migration SQL, use `runMigrations()` so framework-supported compatibility rewrites and dialect-gated statements stay centralized.
+
+### Raw SQL helpers
+
+- `getDbExec()` — auto-converts `?` params to `$1` for Postgres
+- `isPostgres()` — runtime dialect check
+- `intType()` — returns correct integer type for the dialect
+
+### Never
+
+Never write SQLite-only syntax in product code or docs examples: `INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`. When writing docs, say "SQL database" — not "SQLite".
+
+Never write Postgres-only syntax in shared app code either: `ILIKE`, `::type` casts, `jsonb_*`, `RETURNING` assumptions, serial/identity syntax, `ON CONFLICT` upserts, or `ALTER ... TYPE` unless the code is inside a dialect-gated migration block. Prefer Drizzle APIs or framework helpers.
+
+When giving deployment guidance, be precise about durability: local SQLite is the development fallback, while production needs a persistent `DATABASE_URL`. Do not steer users to Turso as the only path; it is one option among Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and managed platform SQL environments when available.
+
+## Hosting Agnostic
+
+The server runs on **Nitro** with **H3** as the HTTP framework. Templates must be deployable to any Nitro-supported target.
+
+### Never use Express
+
+All server code uses H3/Nitro: `defineEventHandler`, `readBody`, `getMethod`, `setResponseHeader`, etc. Express is not a dependency. If you see Express types or patterns anywhere, replace them with H3 equivalents.
+
+### No platform-specific config in scaffolded template source
+
+Files like `netlify.toml`, `wrangler.toml`, `vercel.json`, and `netlify/functions/` must NOT appear in the CLI scaffold source (`packages/core/src/templates/`) — apps generated for users stay hosting-agnostic, with platform configuration living in CI/hosting dashboards.
+
+**Exception:** this monorepo's own first-party deployed apps (`templates/*/netlify.toml`, the root `wrangler-*.toml` files) are deployment artifacts of _this_ repo (mail.agent-native.com, etc.) and are expected to exist. Do not delete them as if they were accidental cruft — the rule above is about what gets scaffolded into a new app, not about this repo's deploy configs.
+
+### No Node APIs in server routes/plugins
+
+Never use `fs`, `child_process`, or `path` in server routes and plugins. Use Nitro abstractions. (Actions in `actions/` run in Node.js and can use Node APIs freely.)
+
+### No persistent-process assumptions
+
+Never assume a persistent server process. Use the SQL database for all state.
+
+## Related Skills
+
+- `storing-data` — Schema patterns and the core SQL stores
+- `server-plugins` — Framework routes and H3 handler patterns
+- `security` — SQL injection prevention via parameterized queries