Agent Native Docs

---
name: agent-native-docs
description: >-
  How to find version-matched Agent-Native framework docs and source bundled in
  node_modules. Use before implementing or answering questions about
  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
  features.
scope: dev
metadata:
  internal: true
---

# Agent-Native Docs Lookup

## Rule

Before implementing or explaining non-trivial Agent-Native behavior, read the
version-matched docs installed with `@agent-native/core`. When examples,
imports, or implementation details matter, inspect the packaged source corpus
too.

## Why

Generated apps and workspaces may be on a different framework version than the
public docs or model memory. The installed package is the source that matches
the app in front of you. It also includes a source-only corpus of first-party
templates so agents can replicate current best-practice patterns without needing
the framework monorepo checkout.

## How

From a generated app directory:

```bash
pnpm action framework-search --pattern "defineAction"
pnpm action framework-search --pattern "templates/*/actions/*.ts" --mode glob --scope source
pnpm action framework-search --pattern "Agent(?:Panel|Sidebar)" --mode regex --scope source
```

Use `framework-search` first when a question may cross the docs and source
boundary. It searches the version-matched framework docs, runtime-visible
skills, readable Core or Toolkit package source, and first-party template
corpus in one bounded read-only call. Use `scope: docs` or `scope: source` to
narrow it, then use the existing focused readers for the page or file you need.

The same tool is available in the headless `pnpm agent` loop and every built-in
app agent. Its default substring mode is safest for ordinary questions; use
`glob` for wildcard paths, `sql-like` for `%` and `_` wildcards, and `regex`
for precise structural matches. Results are bounded, so refine the pattern or
path instead of treating a truncated result as exhaustive.

From a generated app directory, the lower-level readers remain available:

```bash
pnpm action docs-search --query "<feature>"
pnpm action docs-search --slug <slug>
pnpm action docs-search --list
pnpm action source-search --query "<pattern>"
pnpm action source-search --path templates/plan/AGENTS.md
pnpm action source-search --path templates/chat/actions/hello.ts
pnpm action source-search --list
```

The headless `pnpm agent` loop and built-in app agent also expose read-only
`framework-search`, `docs-search`, and `source-search` tools. Use the unified
tool for discovery, then the focused tools for full page or file reads.

If the action runner is unavailable, search the package directly:

```bash
rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
```

Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
under `node_modules/@agent-native/core/docs/content/`. For template examples,
read files under `node_modules/@agent-native/core/corpus/templates/`. The corpus
carries templates only; for Core's own implementation read
`node_modules/@agent-native/core/dist/` (compiled sources plus `.d.ts`).

Toolkit ships readable TypeScript under
`node_modules/@agent-native/toolkit/src/`. Read
`customizing-agent-native` before taking ownership of a shared component: inspect package
source as a read-only reference, then configure, compose, or eject the smallest
supported unit into app-owned source. Preserve public actions, application
state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
deep-import its private source. Manual copying is only the fallback described by
an unknown third-party package's add-style blueprint.

## Reuse Proven Patterns (rg + cp)

Version-matched installed source outranks web docs or memory: it is the exact
code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
holds source for every first-party template, not just the one this app started
from, so a pattern from the mail template is fair game for a tasks app. Grep
across it, then copy a whole file as a starting point instead of writing the
pattern from scratch:

```bash
# Find how other templates solved a similar problem
rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates

# Grab a proven action file as a starting point, then adapt names/schema
cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
   actions/archive-item.ts

# Read the framework's own implementation behind an API
rg -n "defineAction" node_modules/@agent-native/core/dist/action.js
```

Copying template-level app code (actions, components, skill files) is the
expected reuse path — templates exist to be forked. This is different from
copying `core`/`toolkit` **runtime internals**: for those, follow
`customizing-agent-native`'s configure/compose/eject ladder instead of
hand-duplicating framework logic.

## Useful Slugs

| Need                           | Slugs                                                         |
| ------------------------------ | ------------------------------------------------------------- |
| Actions and typed client calls | `actions`, `client`                                           |
| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
| UI state visible to the agent  | `context-awareness`                                           |
| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
| Automations and schedules      | `automations`, `recurring-jobs`                               |
| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |

## Don't

- Do not rely on memory for framework APIs when package docs are present.
- Do not add custom REST wrappers for app data before reading `actions`.
- Do not add inline LLM calls before reading `using-your-agent` and
  `agent-surfaces`.
- Do not copy framework runtime internals when a public API or narrow UI copy
  will do; read `customizing-agent-native` for the supported override ladder.

## Authoring visual docs blocks

Treat the shared `Diagram` block as a renderer, not as a reason to style every
docs UI as a sketch. Use the hand-drawn font and Rough.js only for actual
diagrams or wireframes that communicate structure, flow, or a design draft.
For polished UI-like content - cards, logo walls, tables, controls, or product
shells — set `renderMode="design"` (and usually `frame="hide"` when the block
is the content itself). Design mode preserves normal docs typography and
disables the Rough.js overlay. Keep `data-rough` only on elements intentionally
sketched inside a real diagram.