verse-quote-app/AGENTS.md

Verse — Agent Guide

Verse is a quote app built on poems: browse, search, and favorite quotes drawn from poems, or submit new ones. It started from the agent-native chat template, but the primary surface is the quotes UI at / — chat lives at /chat and is a secondary way to reach the same actions (see "Domain & Actions" below).

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.

Domain & Actions

Data model: poems (author, title, source, year) → quotes (text, tags, is_user_submitted) → favorites (quote_id, visitor_id). visitor_id is an anonymous per-browser id (localStorage), not a login — there is no user account system in this app; AUTH_DISABLED=true by default since no Zitadel client is configured for this instance.

• list-quotes (GET) — browse/search quotes. Optional tag, author, search (free text over quote + poem title), visitorId (marks isFavorited on each result), favoritesOnly, limit. Use this for any "show me quotes about X" / "quotes by Y" request.
• get-random-quote (GET) — one random quote, optionally filtered by tag. Use for "quote of the day" / "surprise me" requests.
• create-quote (POST) — submit a new quote. Requires text, author, poemTitle; optional source, year, tags. Creates the poem record if author+title doesn't already exist (case-sensitive exact match). Marks the quote is_user_submitted: true.
• toggle-favorite (POST) — favorite/unfavorite a quote for a visitorId (toggles based on current state, no separate favorite/unfavorite actions). Returns { favorited, favoriteCount }.
• list-favorites (GET) — all quotes a visitorId has favorited, most recent first. Requires visitorId.

All five are callable from chat and from the React UI via useActionQuery/useActionMutation — there is no separate /api/* REST layer. Every action call emits an OpenTelemetry span, a structured log line, and increments a call counter, exported over OTLP to the shared Grafana LGTM stack (see server/otel.ts).

Application State

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