# {{APP_NAME}} — Agent Guide

This is an agent-native app: the UI and agent share SQL state and the same
action surface. Use the app's existing patterns before adding new ones.

## Skills

Read the matching skill before implementation. Before building common workspace or agent UI, read `agent-native-toolkit` and `customizing-agent-native` for the
configure → compose → eject ladder. Start with `actions` for app operations,
`storing-data` for persistence, `real-time-sync` for live updates, and
`security` for auth, access, and secrets. Use `adding-a-feature` for new
cross-cutting work and `self-modifying-code` when changing app source.

## Core rules

- Store structured state in SQL through Drizzle; store large files in configured
  file/blob storage and persist only URLs, ids, or opaque handles.
- Normal app data must flow through actions.
- Do not create `/api/*` routes that only call, repackage, or proxy an action.
- Define app operations with `defineAction` in `actions/`. The agent and UI
  call the same action surface; do not duplicate an action with a JSON route.
- If you are about to add `server/routes/api/`, stop and write an action
  instead, except for uploads, streaming, webhooks, OAuth callbacks, public
  unauthenticated URLs, or non-JSON responses.
- Keep database code provider-agnostic and migrations additive. Do not use
  adapter-only database methods or production schema push commands.
- All AI work goes through the agent chat. UIs do not call model providers.
- Keep application state in SQL so the agent can read navigation, selection,
  and focused-object context.
- Never hardcode keys, tokens, webhook URLs, private data, or credential-like
  literals. Use secrets, OAuth, or obvious placeholders.
- A missing or unreadable value must stay distinguishable from success. Throw or
  return an explicit error instead of silently falling back to an empty value.

## Application state

Use the existing `application_state` helpers for navigation and selection. Keep
the shape small and explicit; include the current route/view and the selected
object id when the UI has one.

## Actions

Actions in `actions/` are callable from the agent, UI hooks, HTTP, MCP, A2A,
and CLI where enabled. Validate inputs with Zod, return structured data, and
scope reads and writes to the signed-in user or organization. Prefer
`useActionQuery` and `useActionMutation` in browser code.

## Authentication and access

Auth is real Better Auth in development and production. Use `getSession()` or
the shared request context and fail closed when there is no session. Never use a
sentinel identity such as `local@localhost`. Tables with ownable columns need
scoped reads and writes through the framework access helpers.

## UI and sync

Use the shared toolkit and shadcn primitives for standard controls. Keep UI
optimistic where safe, roll back failed mutations, and use `useDbSync()` or
action query invalidation to reflect agent writes without a manual refresh.

## Documentation lookup

Version-matched docs and source examples ship with `@agent-native/core`. Use
`pnpm action docs-search --query "<topic>"` and
`pnpm action source-search --query "<pattern>"`; read the relevant local skill
before relying on a framework API. Do not edit `node_modules` or deep-import
private package internals.

## Verification

Match checks to the change: run the existing focused tests, typecheck, and
formatter. For a user-facing template change, record a changelog entry from
the app with `agent-native changelog add` when appropriate.