@agent-native/core 0.14.8 → 0.15.1

package/src/templates/default/AGENTS.md

@@ -9,7 +9,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 1. **Shared SQL database** -- All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
 2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
 3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`.
-4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync.
+4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` (auto-covered) or fold `useChangeVersions([<source>, "action"])` into raw `useQuery` keys. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 
 ### Authentication
@@ -90,28 +90,31 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-| Skill                 | When to read                                                    |
-| --------------------- | --------------------------------------------------------------- |
-| `storing-data`        | Before storing or reading any app state                         |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                        |
-| `actions`             | Before creating or modifying actions                            |
-| `real-time-sync`      | Before wiring up real-time UI sync                              |
-| `self-modifying-code` | Before editing source, components, or styles                    |
-| `capture-learnings`   | Before recording user preferences or corrections                |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout  |
-| `agent-engines`       | Before switching LLM providers or registering a custom engine   |
-| `notifications`       | Before surfacing alerts/progress to the user or adding channels |
-| `progress`            | Before running any task that takes more than a few seconds      |
+| Skill                 | When to read                                                                      |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
+| `storing-data`        | Before storing or reading any app state                                           |
+| `delegate-to-agent`   | Before adding LLM calls or AI delegation                                          |
+| `actions`             | Before creating or modifying actions                                              |
+| `self-modifying-code` | Before editing source, components, or styles                                      |
+| `capture-learnings`   | Before recording user preferences or corrections                                  |
+| `frontend-design`     | Before building or restyling any UI component, page, or layout                    |
+| `shadcn-ui`           | Before adding, updating, or debugging shadcn/ui components                        |
+| `agent-engines`       | Before switching LLM providers or registering a custom engine                     |
+| `notifications`       | Before surfacing alerts/progress to the user or adding channels                   |
+| `progress`            | Before running any task that takes more than a few seconds                        |
 
 ## When Adding Features
 
-As you build out this app, follow this checklist for each new feature:
+**Read the `adding-a-feature` skill first** — it has the full four-area checklist (UI / Action / Skills / App-State). Quick summary:
 
-1. **Add navigation state entries** -- extend `app/hooks/use-navigation-state.ts` to track new routes
-2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
-3. **Create domain actions** -- add scripts for CRUD operations on new data models
-4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
-5. **Update this AGENTS.md** -- add the new actions, state keys, and common tasks
+1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes
+2. **Enhance view-screen** — make the view-screen script return relevant context for the new view
+3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models
+4. **Wire UI for auto-refresh** — use `useActionQuery` (auto-covered) OR fold `useChangeVersions([<source>, "action"])` into raw `useQuery` keys with `placeholderData`. When the agent mutates this data, the UI must reflect the change without a manual refresh. See `real-time-sync` skill.
+5. **Create domain skills** — add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
+6. **Update this AGENTS.md** — add the new actions, state keys, and common tasks
 
 ---
 

package/src/templates/default/actions/navigate.ts

@@ -35,6 +35,9 @@ export async function run(args: Record<string, string>): Promise<string> {
   const nav: Record<string, string> = {};
   if (args.view) nav.view = args.view;
   if (args.path) nav.path = args.path;
+  // Unique-per-write token so the UI's `use-navigation-state` hook can dedup
+  // race-driven re-reads of the same command.
+  nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   await writeAppState("navigate", nav);
   return `Navigating to ${args.view || args.path}`;
 }

package/src/templates/default/app/hooks/use-navigation-state.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useLocation, useNavigate } from "react-router";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import {
@@ -10,6 +10,10 @@ import {
 export interface NavigationState {
   view: string;
   path?: string;
+  /** Optional unique-per-write token. Used by the UI to dedup the same
+   * command being re-read when the fire-and-forget DELETE below loses its
+   * race against the next polling refetch. */
+  _writeId?: string;
 }
 
 export function useNavigationState() {
@@ -31,7 +35,11 @@ export function useNavigationState() {
     }).catch(() => {});
   }, [location.pathname]);
 
-  const { data: navCommand } = useQuery({
+  // Default React Query structuralSharing reuses the previous reference when
+  // the JSON is unchanged, so repeated invalidations driven by `useDbSync`
+  // (which fire on every relevant app-state event) don't re-fire the
+  // useEffect with a brand-new object containing the same command.
+  const { data: navCommand } = useQuery<NavigationState | null>({
     queryKey: ["navigate-command"],
     queryFn: async () => {
       const res = await fetch(
@@ -39,19 +47,35 @@ export function useNavigationState() {
       );
       if (!res.ok) return null;
       const data = await res.json();
-      return data ? { ...data, _ts: Date.now() } : null;
+      return data ?? null;
     },
     refetchInterval: 2_000,
-    structuralSharing: false,
   });
 
+  const lastProcessedDedupKeyRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (!navCommand) return;
+    const cmd = navCommand;
+    const dedupKey =
+      cmd._writeId ?? JSON.stringify({ view: cmd.view, path: cmd.path });
+    if (lastProcessedDedupKeyRef.current === dedupKey) {
+      // Same command we already handled — the consume-DELETE races against
+      // the next polling refetch, so when it loses the same command can show
+      // up again. Re-fire DELETE and bail rather than navigate again.
+      fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+        method: "DELETE",
+        headers: { "X-Agent-Native-CSRF": "1" },
+      }).catch(() => {});
+      qc.setQueryData(["navigate-command"], null);
+      return;
+    }
+    lastProcessedDedupKeyRef.current = dedupKey;
+
     fetch(agentNativePath("/_agent-native/application-state/navigate"), {
       method: "DELETE",
       headers: { "X-Agent-Native-CSRF": "1" },
     }).catch(() => {});
-    const cmd = navCommand as NavigationState;
 
     const path = routerPath(cmd.path || pathFromView(cmd.view));
     navigate(path);

package/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: a2a-protocol
+description: >-
+  How agents call other agents via the A2A (agent-to-agent) JSON-RPC protocol.
+  Use when enabling inter-agent communication, exposing agent skills to other
+  agents, or calling external agents from scripts.
+---
+
+# A2A Protocol (Agent-to-Agent)
+
+## Rule
+
+Agents can call other agents using the A2A protocol. This is a JSON-RPC-based protocol for agent discovery and communication. Use it when work should go to a different agent entirely — not the local agent chat.
+
+## Why
+
+Agent-native apps don't exist in isolation. A mail agent might need analytics data. A calendar agent might need to search issues. A2A lets agents discover each other, send messages, and receive structured results — all over HTTP with bearer token auth.
+
+## How to Enable A2A (Server Side)
+
+Add `mountA2A()` to a server plugin:
+
+```ts
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  const app = nitro.h3App;
+
+  mountA2A(app, {
+    name: "Analytics Agent",
+    description: "Queries analytics data across providers",
+    version: "1.0.0",
+    skills: [
+      {
+        id: "query-data",
+        name: "Query Data",
+        description: "Run analytics queries across connected data sources",
+        tags: ["analytics", "data"],
+        examples: ["What were last week's signups?", "Show conversion rates"],
+      },
+    ],
+    apiKeyEnv: "A2A_API_KEY", // env var holding the bearer token
+    streaming: true,          // enable message/stream method
+  });
+});
+```
+
+This mounts the agent-native A2A endpoints:
+
+- `GET /.well-known/agent-card.json` — public agent discovery (no auth required)
+- `POST /_agent-native/a2a` — primary JSON-RPC endpoint (bearer token auth required)
+
+The client may fall back to `POST /a2a` for external or legacy peers that only
+expose that simple path. New agent-native apps should document and call the
+`/_agent-native/a2a` endpoint.
+
+## The Config Object
+
+```ts
+interface A2AConfig {
+  name: string;           // agent display name
+  description: string;    // what this agent does
+  version?: string;       // semver version (default: "1.0.0")
+  skills: AgentSkill[];   // capabilities this agent exposes
+  handler?: A2AHandler;   // custom message handler
+  apiKeyEnv?: string;     // env var name for bearer token auth
+  streaming?: boolean;    // enable streaming responses
+}
+
+interface AgentSkill {
+  id: string;             // unique skill identifier
+  name: string;           // human-readable name
+  description: string;    // what this skill does
+  tags?: string[];        // categorization tags
+  examples?: string[];    // example prompts
+}
+```
+
+## Agent Card
+
+The agent card is auto-generated at `GET /.well-known/agent-card.json`. Other agents fetch this to discover what skills are available:
+
+```json
+{
+  "name": "Analytics Agent",
+  "description": "Queries analytics data across providers",
+  "url": "https://analytics.example.com",
+  "version": "1.0.0",
+  "protocolVersion": "0.3",
+  "capabilities": { "streaming": true },
+  "skills": [
+    {
+      "id": "query-data",
+      "name": "Query Data",
+      "description": "Run analytics queries across connected data sources"
+    }
+  ]
+}
+```
+
+## Calling Another Agent
+
+### Simple: `callAgent()` (text in, text out)
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+const answer = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+// answer is a plain string
+```
+
+### Advanced: `A2AClient` (full control)
+
+```ts
+import { A2AClient } from "@agent-native/core/a2a";
+
+const client = new A2AClient(
+  "https://analytics.example.com",
+  process.env.ANALYTICS_A2A_KEY,
+);
+
+// Discover agent capabilities
+const card = await client.getAgentCard();
+
+// Send a message and get a task back
+const task = await client.send({
+  role: "user",
+  parts: [{ type: "text", text: "What were last week's signups?" }],
+});
+// task.status.state === "completed"
+// task.status.message.parts[0].text === "Last week: 1,247 signups..."
+
+// Stream responses
+for await (const update of client.stream({
+  role: "user",
+  parts: [{ type: "text", text: "Detailed breakdown by day" }],
+})) {
+  console.log(update.status.state, update.status.message);
+}
+```
+
+## JSON-RPC Methods
+
+| Method           | Purpose                          | Auth required |
+| ---------------- | -------------------------------- | ------------- |
+| `message/send`   | Send a message, get a task back  | Yes           |
+| `message/stream` | Send a message, stream responses | Yes           |
+| `tasks/get`      | Get task status by ID            | Yes           |
+| `tasks/cancel`   | Cancel a running task            | Yes           |
+
+## Task Lifecycle
+
+Tasks go through these states:
+
+```
+submitted → working → completed
+                    → failed
+                    → canceled
+                    → input-required
+```
+
+- **submitted** — message received, not yet processing
+- **working** — agent is processing the request
+- **completed** — agent finished, result in `status.message`
+- **failed** — agent encountered an error
+- **canceled** — task was canceled via `tasks/cancel`
+- **input-required** — agent needs more information from the caller
+
+## Security
+
+A2A uses bearer token auth. The server reads the token from the environment variable specified by `apiKeyEnv`:
+
+- Set `A2A_API_KEY=my-secret-token` in the server's environment
+- Callers pass it as `Authorization: Bearer my-secret-token`
+- The agent card endpoint (`/.well-known/agent-card.json`) is public — no auth needed for discovery
+
+## Message Parts
+
+Messages contain typed parts:
+
+| Part type | Fields                              | Use for                    |
+| --------- | ----------------------------------- | -------------------------- |
+| `text`    | `{ type: "text", text: "..." }`     | Natural language messages  |
+| `file`    | `{ type: "file", file: { ... } }`   | Files (bytes or URI)       |
+| `data`    | `{ type: "data", data: { ... } }`   | Structured JSON data       |
+
+## Example: Cross-Agent Workflow
+
+A mail agent calls an analytics agent to include data in an email draft:
+
+```ts
+// actions/draft-with-analytics.ts
+import { callAgent } from "@agent-native/core/a2a";
+import { writeAppState } from "@agent-native/core/application-state";
+
+export default async function (args: string[]) {
+  // Ask the analytics agent for data
+  const stats = await callAgent(
+    process.env.ANALYTICS_AGENT_URL!,
+    "Summarize last week's key metrics in 3 bullet points",
+    { apiKey: process.env.ANALYTICS_A2A_KEY },
+  );
+
+  // Create a draft with the analytics data
+  await writeAppState("compose-analytics-report", {
+    id: "analytics-report",
+    to: "team@example.com",
+    subject: "Weekly Analytics Summary",
+    body: `Hi team,\n\nHere are last week's numbers:\n\n${stats}\n\nBest`,
+    mode: "compose",
+  });
+}
+```
+
+## All Types
+
+All types are exported from `@agent-native/core/a2a`:
+
+```ts
+import type {
+  A2AConfig,
+  A2AHandler,
+  A2AHandlerContext,
+  A2AHandlerResult,
+  AgentCard,
+  AgentSkill,
+  AgentCapabilities,
+  Task,
+  TaskState,
+  TaskStatus,
+  Message,
+  Part,
+  TextPart,
+  FilePart,
+  DataPart,
+  Artifact,
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from "@agent-native/core/a2a";
+```
+
+## Related Skills
+
+- **delegate-to-agent** — For work the local agent handles. Use A2A when the work goes to a different agent.
+- **scripts** — A2A calls typically happen in scripts
+- **storing-data** — Results from A2A calls are stored in SQL like any other data

package/src/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: actions
+description: >-
+  How to create and run agent actions. Actions are the single source of truth
+  for app operations — the agent calls them as tools, the frontend calls them
+  as HTTP endpoints. Use when creating a new action, adding an API integration,
+  or wiring up frontend data fetching.
+---
+
+# Agent Actions
+
+## Rule
+
+Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, and the framework auto-exposes them as HTTP endpoints at `/_agent-native/actions/:name`. The frontend calls those endpoints using React Query hooks. No duplicate `/api/` routes needed.
+
+## Why
+
+Actions give the agent callable tools with structured input/output, AND they give the frontend type-safe HTTP endpoints automatically. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
+
+## How to Create an Action
+
+Use `defineAction` with a Zod schema (required for new actions):
+
+```ts
+// actions/list-meals.ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+import { getDb } from "../server/db/index.js";
+import { meals } from "../server/db/schema.js";
+
+export default defineAction({
+  description: "List all meals",
+  schema: z.object({
+    date: z.string().describe("Filter by date (YYYY-MM-DD)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    // args is fully typed: { date: string }
+    const db = getDb();
+    const rows = await db.select().from(meals);
+    return rows; // Return objects/arrays, NOT JSON.stringify()
+  },
+});
+```
+
+The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages (400 for HTTP, error result for agent), full TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
+
+Tips:
+- Use `.describe()` for parameter descriptions
+- Use `.optional()` for optional params
+- Use `z.coerce.number()` / `z.coerce.boolean()` for params that arrive as strings from HTTP
+- Use `z.enum(["draft", "published"])` for constrained values
+
+The legacy `parameters` field (plain JSON Schema object) still works as a fallback but does not provide runtime validation or type inference.
+
+### The `http` Option
+
+Controls how the action is exposed as an HTTP endpoint:
+
+| Value                     | Behavior                                                    | Use for                          |
+| ------------------------- | ----------------------------------------------------------- | -------------------------------- |
+| _(omitted)_               | Auto-exposed as `POST /_agent-native/actions/:name`         | Write operations (default)       |
+| `{ method: "GET" }`       | Auto-exposed as `GET /_agent-native/actions/:name`          | Read-only queries                |
+| `{ method: "PUT" }`       | Auto-exposed as `PUT /_agent-native/actions/:name`          | Update operations                |
+| `{ method: "DELETE" }`    | Auto-exposed as `DELETE /_agent-native/actions/:name`       | Delete operations                |
+| `{ method: "GET", path: "custom" }` | Auto-exposed as `GET /_agent-native/actions/custom` | Custom route path                |
+| `false`                   | Agent-only, never exposed as HTTP                           | `navigate`, `view-screen`, internal actions |
+
+### Screen Refresh (automatic)
+
+The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the server emits a poll event that the client's `useDbSync` picks up and uses to invalidate `["action"]` React Query keys — so `list-*` / `get-*` hooks refetch without a full page reload.
+
+Rules:
+
+- `http: { method: "GET" }` → read-only, does NOT trigger a refresh (inferred automatically).
+- Any other action (default `POST`, `PUT`, `DELETE`, or `http: false`) → treated as mutating, triggers a refresh on success.
+- To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
+- To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
+
+Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
+
+### Return Values
+
+Actions should return **structured data** (objects, arrays) — not `JSON.stringify()`. The framework serializes the response automatically. If you return a string, the framework tries to parse it as JSON for a clean response.
+
+```ts
+// Good — return structured data
+run: async (args) => {
+  const events = await fetchEvents(args.from, args.to);
+  return events;
+}
+
+// Bad — don't stringify
+run: async (args) => {
+  const events = await fetchEvents(args.from, args.to);
+  return JSON.stringify(events, null, 2);
+}
+```
+
+## Frontend Hooks
+
+The frontend calls action endpoints using React Query hooks from `@agent-native/core/client`:
+
+### `useActionQuery` — for GET actions
+
+```ts
+import { useActionQuery } from "@agent-native/core/client";
+
+function MealList() {
+  // Types are auto-inferred from the action's schema + return type — no manual generic needed
+  const { data: meals } = useActionQuery("list-meals", {
+    date: "2025-01-01",
+  });
+  return <ul>{meals?.map((m) => <li key={m.id}>{m.name}</li>)}</ul>;
+}
+```
+
+### `useActionMutation` — for POST/PUT/DELETE actions
+
+```ts
+import { useActionMutation } from "@agent-native/core/client";
+
+function AddMealButton() {
+  // Types are auto-inferred — no manual generic needed
+  const { mutate } = useActionMutation("log-meal");
+  return (
+    <button onClick={() => mutate({ name: "Salad", calories: 350 })}>
+      Log Meal
+    </button>
+  );
+}
+```
+
+**Do NOT use manual type generics** like `useActionQuery<Meal[]>(...)`. Types are inferred automatically from `.generated/action-types.d.ts`, which is auto-generated by a Vite plugin.
+
+Mutations automatically invalidate all `["action"]` query keys on success, so GET queries refetch.
+
+## How to Run (Agent)
+
+```bash
+pnpm action my-action --input data/source.json --output data/result.json
+```
+
+## Action Dispatcher
+
+The default template uses core's `runScript()` in `actions/run.ts`:
+
+```ts
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
+
+## When You Still Need Custom `/api/` Routes
+
+Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+
+- **File uploads** — actions receive JSON params, not multipart form data
+- **Streaming responses** — SSE or chunked responses that need direct H3 control
+- **Webhooks** — external services POST to a specific URL
+- **OAuth callbacks** — redirect-based flows that need specific URL patterns
+
+If it's a standard CRUD operation or data query, use an action instead.
+
+## Legacy Pattern (bare export)
+
+Older actions use a bare async function export with `parseArgs`:
+
+```ts
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  // ...
+}
+```
+
+This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all new actions.
+
+## Guidelines
+
+- **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
+- **Return structured data.** Return objects/arrays, not `JSON.stringify()`.
+- **Use `http: { method: "GET" }`** for read-only actions. Default is POST.
+- **Use `http: false`** for agent-only actions (`navigate`, `view-screen`).
+- **Use `loadEnv()`** if the action needs environment variables (API keys, etc.).
+- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
+- **Import from `@agent-native/core`** — Don't redefine `parseArgs()` or other utilities locally.
+
+## Common Patterns
+
+**Read action (GET):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "List calendar events",
+  schema: z.object({
+    from: z.string().describe("Start date"),
+    to: z.string().describe("End date"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return await fetchEvents(args.from, args.to);
+  },
+});
+```
+
+**Write action (POST, default):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Log a meal",
+  schema: z.object({
+    name: z.string().describe("Meal name"),
+    calories: z.coerce.number().describe("Calorie count"),
+  }),
+  run: async (args) => {
+    // args.calories is a number — z.coerce.number() handles string-to-number conversion from HTTP
+    const meal = await insertMeal(args);
+    return meal;
+  },
+});
+```
+
+**Agent-only action:**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Navigate the UI to a view",
+  schema: z.object({
+    view: z.string().describe("Target view"),
+  }),
+  http: false,
+  run: async (args) => {
+    await writeAppState("navigate", { command: "go", view: args.view });
+    return "Navigated";
+  },
+});
+```
+
+## Troubleshooting
+
+- **Action not found** — Check that the filename matches the command name exactly. `pnpm action foo-bar` looks for `actions/foo-bar.ts`.
+- **Args not parsing** — Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
+- **Frontend getting 405** — The action's `http.method` doesn't match the hook. Use `useActionQuery` for GET actions, `useActionMutation` for POST/PUT/DELETE.
+- **Frontend getting undefined** — Make sure the action returns structured data, not `JSON.stringify()`.
+
+## Related Skills
+
+- **storing-data** — Actions read/write data in SQL
+- **delegate-to-agent** — The agent invokes actions via `pnpm action <name>`
+- **real-time-sync** — Database writes from actions trigger poll events to update the UI
+- **adding-a-feature** — Actions are area 2 of the four-area checklist