@agent-native/core 0.14.8 → 0.15.0

package/dist/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/dist/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

package/dist/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: adding-a-feature
+description: >-
+  The four-area checklist every new feature must complete. Use when adding any
+  feature, integration, or capability to ensure the agent and UI stay in parity.
+---
+
+# Adding a Feature — The Four-Area Checklist
+
+## Rule
+
+Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
+
+## Why
+
+Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
+
+## The Checklist
+
+When you add a new feature, work through these four areas in order:
+
+### 1. UI Component
+
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations — you rarely need custom `/api/` routes.
+
+**Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
+
+- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
+- **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
+
+  ```tsx
+  import { useChangeVersions } from "@agent-native/core/client";
+  import { useQuery } from "@tanstack/react-query";
+
+  const v = useChangeVersions(["dashboards", "action"]);
+  useQuery({
+    queryKey: ["dashboard", id, v],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // no flicker on refetch
+  });
+  ```
+
+  See the `real-time-sync` skill for the full pattern and source catalog.
+
+### 2. Action
+
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the framework auto-exposes it as an HTTP endpoint at `/_agent-native/actions/:name` for the UI to call. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+### 3. Skills / Instructions
+
+Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
+
+### 4. Application State Sync
+
+Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
+
+## Examples
+
+### Adding "compose email" to a mail app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
+| Action          | `manage-draft` action (create/update/delete drafts), `send-email` action                 |
+| Skills/AGENTS   | Document compose state shape, draft lifecycle, action args in AGENTS.md                  |
+| App-state sync  | `compose-{id}` keys for each draft tab, `navigation` includes compose state              |
+
+### Adding "create form" to a forms app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
+| Action          | `create-form` action, `update-form` action, `list-forms` action (GET)                    |
+| Skills/AGENTS   | Document form schema shape, field types, validation rules in AGENTS.md                   |
+| App-state sync  | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
+
+### Adding "chart type" to an analytics app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | New chart component, chart type selector in dashboard                                    |
+| Action          | `create-chart` or `update-dashboard` action that sets chart type and config              |
+| Skills/AGENTS   | Document supported chart types, config options, data requirements                        |
+| App-state sync  | `navigation` includes selected chart/dashboard, `view-screen` returns chart config       |
+
+## Adding a new route
+
+Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
+
+**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
+
+- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
+- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
+- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
+
+See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
+
+## Anti-Patterns
+
+- **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
+- **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
+- **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle. Actions are auto-exposed as HTTP endpoints — use `useActionQuery`/`useActionMutation` instead.
+- **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
+- **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
+
+## Verification
+
+After completing all four areas, verify:
+
+1. Can the user perform the operation from the UI?
+2. Can the agent perform the same operation via actions?
+3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
+4. Can the agent navigate to the feature view via the `navigate` action?
+5. Is the feature documented in AGENTS.md with action names and args?
+
+## One more area — sharing
+
+If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
+
+TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
+
+## Related Skills
+
+- **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
+- **context-awareness** — How to expose UI state to the agent (area 4 in detail)
+- **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **create-skill** — How to create skills for new patterns (area 3 in detail)
+- **storing-data** — Where to store the feature's data
+- **real-time-sync** — How the UI stays in sync when the agent writes data