# Chat — Agent Guide

Chat is the minimal chat-first agent-native app template. Keep chat as the
primary surface, add actions for real capabilities, and add screens only when a
workflow needs durable UI around the conversation.

## Core Rules

- Store large file/blob payloads in configured file/blob storage, not SQL: no
  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
  or `resources`; persist URLs, ids, or handles instead.
- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
- Follow the root framework contract: data in SQL, actions first, application
  state for navigation/selection, and shared agent chat for AI work.
- Scale effort to the task. A small, well-specified change is a short read, the
  edit, and the app's existing checks (`pnpm typecheck`, formatter, existing
  tests) — not a codebase survey, unrequested tests, or browser automation.
- Use actions for app operations and keep frontend/API parity.
- Do not add `/api/*` routes for app data. If you are about to create a file
  under `server/routes/api/`, or middleware to guard one, stop and write a
  `defineAction` instead. The only exceptions are uploads, streaming, inbound
  webhooks, OAuth callbacks, public unauthenticated URLs, and non-JSON
  responses — not auth, settings, search, or CRUD.
- Treat the chat as the default UI. When the user asks for a capability, prefer
  adding or improving the action surface first, then add a page, table, form, or
  widget only when the user needs to inspect, compare, approve, or share durable
  objects.
- If the user wants to plug in their own agent backend, keep the app shell and
  thread UI intact and adapt the chat through the framework's `AgentChatRuntime`
  connector helpers instead of forking the transcript/composer UI.
- Keep the action surface small and orthogonal: every action is a tool in the
  model's context window, so prefer one CRUD-style `update` (patch of fields)
  over many per-field actions, reach for an existing generic query / escape
  hatch (`provider-api-*`, dev `db-query`) before minting a new read action,
  mark UI-only or programmatic actions `agentTool: false` to hide them from the
  model (distinct from `toolCallable: false`, which only gates the extension
  iframe), and delete or hide actions the UI no longer uses. See the `actions`
  skill.
- Keep database code provider-agnostic and additive.
- Use `view-screen` or application state when the active page/selection is
  unclear.
- For new features, update UI, actions, skills/instructions, and application
  state when applicable.

## What This App Does

A minimal stock listing app. Each user keeps a personal list of stock tickers
(symbol, company name, exchange, sector, price, change percent, market cap,
watchlisted) at the `/stocks` page. Chat remains the primary surface for
asking the agent to add, look up, or edit listings; `/stocks` is the durable
UI for browsing, searching, and managing the list at a glance.

## Actions

| Action         | Method | Description                                                             |
| -------------- | ------ | ------------------------------------------------------------------------ |
| `list-stocks`  | GET    | List the current user's stock listings. Supports `search`, `exchange`, `watchlistedOnly`. |
| `get-stock`    | GET    | Get one listing by `id` or `symbol`.                                    |
| `add-stock`    | POST   | Add a new listing (`symbol`, `companyName` required; fails if symbol already listed). |
| `update-stock` | PUT    | Patch a listing by `id` — price, change percent, sector, `watchlisted` ("true"/"false"), etc. |
| `delete-stock` | DELETE | Delete a listing by `id`.                                               |
| `hello`        | GET    | Starter example action.                                                 |
| `navigate`     | agent-only | Navigate the UI to a view/path (adds `view: "stocks"` for `/stocks`).|
| `view-screen`  | agent-only | Read current navigation state; when the user is on `/stocks`, also returns the full stock listing snapshot. |

Stocks are scoped per `ownerEmail` (the authenticated user). Data lives in
the `stocks` table in Postgres (`DATABASE_URL`) in this deployment, or SQLite
at `data/app.db` for local dev without a `DATABASE_URL` — see
`server/db/schema.ts` and `server/plugins/db.ts`.

## Application State

- `navigation` should describe the current view and selected entity ids. The
  default chat view is `chat` at `/`; the stock listing view is `stocks` at
  `/stocks`.
- `navigate` may be used to move the UI when the app supports it.
- `view-screen` is the first tool to call when the user's visible context
  matters.

## Framework Docs Lookup

- Before implementing or explaining non-trivial Agent Native behavior, use the
  `agent-native-docs` skill and the built-in `docs-search` action/tool to read
  the version-matched framework docs bundled with `@agent-native/core`.
- Use the built-in `source-search` action/tool, or search
  `node_modules/@agent-native/core/corpus`, when you need current core or
  first-party template implementation examples.
- Prefer those installed docs over memory or public docs when package APIs,
  generated-app conventions, workspaces, actions, or agent surfaces are involved.
- Before building common workspace or agent UI, read `agent-native-toolkit` to
  inventory existing public kits and installed package seams.
- Read `customizing-agent-native` before overriding the chat shell or shared UI.
  Keep Core thread/runtime behavior and use the supported ladder: configure →
  compose → eject the smallest presentation unit → propose a shared seam.
  Preview before `--apply` and commit `agent-native.ejections.json`.

## Skills

Read the relevant root skill before implementation: `adding-a-feature`,
`actions`, `agent-native-docs`, `agent-native-toolkit`,
`customizing-agent-native`, `storing-data`,
`real-time-sync`, `security`, `delegate-to-agent`, `frontend-design`, `shadcn-ui`, and
`self-modifying-code`.