verse-quote-app/AGENTS.md

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.
• Use actions for app operations and keep frontend/API parity.
• 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.

Application State

• navigation should describe the current view and selected entity ids. The default chat view is chat at /.
• 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.