@agent-native/core 0.114.16 → 0.115.1

package/corpus/templates/content/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,115 @@
+---
+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 core and
+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 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 toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+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 source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+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 full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+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.

package/corpus/templates/content/_gitignore

@@ -0,0 +1,39 @@
+# React Router generated types
+.react-router/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Data
+data/uploads/
+data/settings.json
+data/.sessions.json
+
+# Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
+learnings.md
+
+.vercel/

package/corpus/templates/content/learnings.defaults.md

@@ -0,0 +1,5 @@
+# Learnings
+
+<!-- This file is your app's memory. The AI reads it at the start of every conversation and updates it when it learns something new. -->
+<!-- Your personal learnings.md is gitignored so preferences and private info stay local. -->
+<!-- This defaults file is what new checkouts start with. -->

package/corpus/templates/crm/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,115 @@
+---
+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 core and
+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 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 toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+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 source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+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 full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+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.

package/corpus/templates/crm/.agents/skills/agent-native-toolkit/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: agent-native-toolkit
+description: >-
+  Inventory and ownership rules for shared Agent Native workspace UI. Use
+  before building app chrome, settings, navigation, sharing, collaboration,
+  setup, history, comments, chat rails, agent UX, or repeated workspace behavior.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Discover Before Building
+
+Before creating an app-local version of repeated workspace or agent UI:
+
+1. Check the reusable kits below and the installed package documentation.
+2. Search installed public components and source with `docs-search` and
+   `source-search`.
+3. Run `agent-native eject --list` to see the version-matched units published
+   by the packages installed in this app.
+4. Read `customizing-agent-native` and configure, compose, or eject the
+   smallest unit instead of recreating shared behavior from memory.
+
+Use public package exports at runtime. Published source and ejection manifests
+are discovery and ownership-transfer mechanisms, not private runtime APIs.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: a searchable settings page with account, workspace, AI
+  models, LLM keys, connections, secrets, usage, notifications, changelog, and
+  app-specific panels. Search is on by default; register a `SettingsSearchEntry`
+  per control so users find settings by name across tabs.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **Chat history kit**: presentational chat lists and recent-chat rails belong
+  in Toolkit; Core keeps thread persistence, agent execution, transport, and
+  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+- **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
+  `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
+  Access tabs plus a Personal/Organization scope toggle. The canonical home
+  for context transparency, MCP servers, A2A remote agents, recurring
+  jobs/automations, and external-client connect flows. See the `agent-page`
+  skill.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, React component/hook, and
+   app adapter points.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+7. Keep the component easy to adopt piecemeal: expose props/slots first and
+   ship readable source plus a complete ejection unit so apps can take ownership
+   of the smallest feature when needed. See `customizing-agent-native` for the
+   configure → compose → eject → propose seam ladder.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`

package/corpus/templates/crm/.agents/skills/crm/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: crm
+description: Work with Native SQL or HubSpot/Salesforce CRM using scoped records, field policies, evidence, proposals, and provider data programs.
+---
+
+# CRM Companion
+
+Use actions as the operational source of truth and `shared/crm-contract.ts` as
+the product-model source of truth. This scope supports standalone Native SQL
+and HubSpot/Salesforce Connected/Hybrid behavior.
+
+## Start with the right source
+
+- Use `view-screen` only when the request depends on the current UI view,
+  selection, or saved view. Use `get-crm-overview`, `list-crm-records`, and
+  `get-crm-record` for ordinary CRM reads.
+- Use `sync-crm` for a declared, bounded mirror cohort. It is not an exhaustive
+  provider export.
+- Use `configure-native-crm` to start CRM without an external provider. Native
+  SQL records are local-authoritative and portable across SQLite, Postgres, and
+  D1. Use the normal CRM record, task, view, cadence, and evidence actions;
+  never require a provider connection or call `sync-crm` for Native SQL.
+- After HubSpot or Salesforce is authorized in workspace Connections, use
+  `configure-crm-connection` with the selected provider to register it with
+  CRM. Never pass a token. HubSpot starts with `companies`, `contacts`, and
+  `deals`; Salesforce starts with `Account`, `Contact`, and `Opportunity`.
+- Use `sync-crm` only for the declared recent cohort. HubSpot may be narrowed
+  by deal pipeline ids; Salesforce uses the updated-after boundary for its
+  standard objects. Record detail can perform a scoped read-through refresh;
+  do not treat it as permission for an export-all query.
+- For an endpoint, object, filter, pagination mode, or schema not represented
+  by a CRM action, use `provider-api-catalog`, `provider-api-docs`, then the
+  read-only `provider-api-request` for the selected provider. Before broad work,
+  declare a cohort, selected fields, and a bounded page/row budget. Stage only
+  that result, then use `query-staged-dataset` or a data program to reduce it.
+  Report provider, scope, filters, page/row counts, truncation, and gaps.
+- Always pass the selected workspace `connectionId` for Salesforce provider API
+  reads so its actor-bound OAuth token and instance URL cannot be separated.
+
+## Field, evidence, and credential boundaries
+
+- Credentials exist only in workspace Connections. Never request, paste, log,
+  save, or return a HubSpot or Salesforce token or secret.
+- Treat the upstream CRM as authoritative for remote fields. Only configured
+  allow-listed fields are mirrored. Unknown fields are remote-only; sensitive
+  fields default to redacted and must not be fetched or shown.
+- Salesforce reads must be revalidated against the current connection actor and
+  field permissions. Never infer a user's access from a service-account mirror
+  or from a previously visible local row; fail closed when access is ambiguous.
+- Never save raw provider payloads, media, screenshots, audio, video,
+  transcripts, base64 data, or file bodies in CRM SQL. `attach-call-evidence`
+  stores only a source URL/id, bounded quote, timestamp, speaker, and metadata.
+  For Clips, use only a durable `/share/<id>` or `/r/<id>` page URL with no
+  access token or transcript fragment; never use a `clip.created` event URL.
+- Use `run-crm-signal-trackers` only over evidence already attached to the CRM
+  record. Keyword hits are deterministic. Smart detector and summary requests
+  must go through agent chat, never a direct model call. Persist delegated
+  results with `record-crm-smart-signal` or one atomic
+  `record-crm-call-insight` batch; each quote/timestamp must cite the exact
+  bounded evidence row. Use `review-crm-signal` for human confirmation.
+- Use `create-crm-signal-tracker` to add a keyword or smart tracker, and
+  `manage-crm-signal-tracker` to enable, disable, or delete one tracker with
+  editor access. Tracker management is local configuration only: it never
+  invokes a model or mutates a connected provider. Navigate with
+  `{ view: "settings", settingsSection: "intelligence" }` to open the
+  Intelligence settings tab.
+- Do not identify or merge records by email/domain alone. Provider identity is
+  connection + provider + object type + remote id, and relationships retain
+  direction.
+
+## Safe writes and workflows
+
+- Use `update-crm-record` for a scoped typed edit. Provider writes are
+  prepared as revision-aware, access-checked, idempotent, audited proposals.
+  HubSpot proposals always hand off because HubSpot cannot apply the expected
+  revision atomically. Salesforce conditional-write capability is a
+  prerequisite for a future provider apply, not a reason to claim a write
+  succeeded without a confirmed provider response and the stored approval
+  policy.
+- Agent provider writes default to proposals. For ownership, amount, stage,
+  delete, bulk, or external-side-effect changes, show exact scope and fields,
+  then require approval. Use `list-crm-proposals` and
+  `apply-crm-proposals` to review the change and record the upstream handoff;
+  direct the user to complete it in HubSpot or Salesforce and never claim it
+  was applied without a confirmed adapter result.
+- The only stored delegation pack is `crm-sales-routine-local-v1`. It applies
+  only when a trusted automation trigger supplies that policy id and only to
+  one routine local record update. Do not pass policy ids as action input;
+  provider mutations stay proposal-first and risky, destructive, bulk, or
+  external-effect work stays gated.
+- Native SQL writes are local-authoritative CRM mutations. They remain
+  access-checked, idempotent, and audited, but have no provider handoff or
+  remote revision to claim.
+- Use `list-crm-saved-views` and `save-crm-saved-view` for saved views. Use
+  `list-crm-tasks` and `manage-crm-task` for CRM follow-ups. Use `navigate` to
+  show a requested view instead of merely describing it.
+- Use `install-crm-pipeline-dashboard` to install the owner-scoped Pipeline
+  dashboard. Its stored data program calls the bounded, access-scoped
+  `get-crm-pipeline-data` action through `appAction`; do not reimplement the
+  aggregate with a provider request or put CRM rows in dashboard config. Use
+  `get-crm-dashboard` / `list-crm-dashboards` to inspect dashboards,
+  `save-crm-dashboard` with `expectedUpdatedAt` for safe edits, and
+  `list-crm-dashboard-revisions` / `restore-crm-dashboard-revision` to review
+  or restore prior dashboard configurations.
+- Use `get-crm-automation-recipe` for the default-off Clips call-evidence
+  review recipe after the user explicitly selects a CRM record. The recipe is a
+  configuration aid, not permission to activate an automation. Before enabling
+  it, show the exact Clips-owned `clip.created` trigger, the selected CRM
+  record, and its one bounded local evidence-reference write, then obtain a
+  fresh approval. Use the recipe's exact `call-agent` input and content-bound
+  `approvedActions` grant. The Clips trigger must call
+  `prepare-crm-call-evidence`; never use the event URL or copy media/transcript
+  content. The downstream CRM call may only invoke `attach-call-evidence` for
+  that selected record and cannot create tasks, field updates, proposals, or
+  provider mutations.
+
+## Four-area provider changes
+
+Provider behavior must stay aligned across setup UI, CRM actions, this skill,
+and `application_state`/`view-screen`. Reuse workspace Connections and action
+hooks; do not add a provider-key field, legacy `/api` route, direct browser
+fetch, or provider-specific state outside the shared CRM contract.
+
+## Out of scope
+
+Do not add provider migration, a page builder, or raw provider payload/media in
+CRM SQL. Native SQL supports the canonical CRM objects and generic custom
+records; a separate object-authoring engine is not part of this template.