@agent-native/core 0.118.0 → 0.119.0

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

@@ -1,177 +0,0 @@
----
-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.
-
-## Design-System Boundary
-
-Every app keeps an explicit design-system seam in `app/design-system.ts` using
-`defineDesignSystem` from `@agent-native/toolkit/design-system`, and supplies it
-to `ToolkitProvider`. The semantic contract contains:
-
-- nine leaf components: `ActionButton`, `IconButton`, `TextField`, `TextArea`,
-  `Spinner`, `Skeleton`, `Status`, `Surface`, and `Avatar`
-- eight behavior components: `Tooltip`, `Menu`, `Popover`, `Dialog`, `Picker`,
-  `Checkbox`, `Switch`, and `Tabs`
-
-These are semantic contracts, not styling contracts. An adapter may use
-Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,
-or another React design system. Do not assume CVA, utility classes, or even a
-`className`; behavior adapters may supply their overlay and focus
-implementation wholesale while honoring portal, focus-restoration, keyboard,
-dismissal, ARIA, and z-index interoperability.
-
-Pages, routes, and domain components import ordinary controls through the app's
-local adapter layer, usually `@/components/ui/*`. They must not import
-`@agent-native/toolkit/ui/*` directly. Toolkit feature exports are still the
-right home for shared workspace behavior; their presentation flows through the
-registered semantic components, feature controller, and product-level slots.
-
-Customer adapter packages are normal npm packages imported explicitly by the
-app. Never auto-detect them or load React components from JSON. Run the adapter
-against `@agent-native/toolkit/conformance` in customer CI before adopting it.
-
-## 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`
-
-The shared Account section is the canonical profile surface at
-`/settings#account`. It owns the editable display name and existing avatar
-control through the authenticated `get-user-profile` and `update-user-profile`
-actions. Shared workspace chrome such as `OrgSwitcher` should link to this
-surface rather than creating an app-local profile page.
-
-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. Use Toolkit's `ChatHistoryRail` for the standard
-  five-item sidebar preview and a footer row with New chat followed by an
-  ellipsis disclosure up to fifteen. 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, feature-level headless
-   controller, default view, semantic components, and product-level render
-   slots.
-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.
-8. Keep one controller as the source of truth for the default and custom render
-   paths. A custom design must not fork actions, analytics, async state, or
-   accessibility behavior.
-9. Verify the default adapter and at least one non-Tailwind adapter with the
-   conformance kit, including focus and portal stacking across mixed overlay
-   implementations.
-
-## 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

@@ -1,128 +0,0 @@
----
-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.

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

@@ -1,220 +0,0 @@
----
-name: customizing-agent-native
-description: >-
-  How to configure, compose, or eject Agent Native features into app-owned
-  code. Use when overriding shared components or integrations, customizing a
-  template, adding UI to chat or headless apps, or inspecting package source.
-scope: dev
-metadata:
-  internal: true
----
-
-# Customizing Agent Native
-
-## Rule
-
-Start with the app's registered design system and local UI adapters, then use
-the public feature's props, semantic components, controller, product slots,
-and callbacks. If those seams are not enough, use the eject CLI to transfer
-the smallest supported feature into the app and make that copy app-owned.
-Never edit `node_modules`, deep-import a private source file at runtime, or
-patch an `@agent-native/*` package.
-
-Use this order:
-
-1. Set brand tokens with the build-time theme configuration when tokens are
-   enough.
-2. Register company components in `app/design-system.ts` with
-   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
-3. Configure a public feature through its semantic components, headless
-   controller, and product-level render slots.
-4. Compose app primitives behind the app's local UI adapter layer.
-5. Eject the smallest feature into app-owned source.
-6. Propose a new Toolkit seam when the same override is useful in two apps.
-
-Ejection is for intentional product customization, not for hiding an upgrade
-failure or replacing Core runtime behavior.
-
-## Use A Company Design System
-
-Keep the explicit, typed registration seam in `app/design-system.ts`:
-
-```tsx
-import { defineDesignSystem } from "@agent-native/toolkit/design-system";
-import {
-  AcmeActionButtonAdapter,
-  AcmeDialogAdapter,
-} from "./design-system/acme-adapter";
-
-export const designSystem = defineDesignSystem({
-  name: "Acme",
-  components: {
-    ActionButton: AcmeActionButtonAdapter,
-    Dialog: AcmeDialogAdapter,
-  },
-});
-```
-
-Adapters translate the semantic Toolkit contract into company component props.
-They are ordinary React components and may use MUI-style providers, React Aria,
-CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
-optional interoperability hooks, not Tailwind or CVA requirements.
-
-The contract has nine leaf components (`ActionButton`, `IconButton`,
-`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
-and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
-`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
-behavior, not date picking. Behavior adapters own their portal, focus,
-keyboard, dismissal, and stacking implementation while honoring the semantic
-props and `portalContainer` interop contract.
-
-App product code imports standard controls from its local adapter path, usually
-`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
-pages, routes, or domain components. That bypasses the app seam and makes a
-future design-system replacement incomplete. Toolkit feature packages remain
-valid imports; configure their presentation through the registered semantic
-components, controller, and product slots.
-
-Run the published conformance kit against a complete adapter in its own CI:
-
-```tsx
-import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
-import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
-
-await assertDesignSystemConformance({
-  adapterName: "Acme",
-  components,
-  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
-});
-```
-
-New components and optional props are minor contract changes. Required props,
-removed APIs, or behavioral changes require a new contract major.
-
-## Customize A Shared Feature
-
-Prefer feature-level headless controllers over rebuilding individual widgets.
-One controller must power both the Toolkit default view and every custom render
-path so behavior, actions, analytics, accessibility state, and error handling
-cannot drift. Use a product-level render slot to replace the view while keeping
-that controller. Eject only when the controller and slots cannot express the
-required product behavior.
-
-## Eject A Feature
-
-Discover and inspect the ejection units published by installed first-party
-packages before changing source:
-
-```bash
-agent-native eject --list
-agent-native eject inspect <unit>
-agent-native eject <unit> --app <app>
-agent-native eject <unit> --app <app> --apply
-```
-
-The command is dry-run by default. It prints the file closure, consumer import
-rewrites, protected package contracts, and verification commands before
-writing. `--apply` copies the package-version-matched source into the app and
-rewrites only imports covered by the unit manifest.
-
-Every first-party public ejection unit must have a complete manifest. If one is
-missing, treat that as a framework coverage bug instead of inventing a copy
-recipe. For an unknown third-party package, use the emitted add-style blueprint
-as a starting point. Protected runtime behavior is never copied; follow the
-reported configuration, adapter, or extension seam instead.
-
-Applied ejections are recorded in the committed
-`agent-native.ejections.json`, including package version, manifest digest,
-target hashes, and import rewrites. Use the recorded state to review drift or
-undo an unchanged ejection:
-
-```bash
-agent-native eject diff <unit> --app <app>
-agent-native eject restore <unit> --app <app>
-agent-native eject restore <unit> --app <app> --apply
-```
-
-Restore is hash-gated. It refuses to remove locally edited files or reverse
-changed imports and prints their diff instead. Keep an edited ejection as
-app-owned code, or reconcile those edits before restoring it.
-
-## Find The Installed Implementation
-
-Use the source that matches the installed package version:
-
-```bash
-pnpm action docs-search --query "<component or feature>"
-pnpm action source-search --query "<component or symbol>"
-rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
-rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
-```
-
-- Toolkit publishes readable TypeScript under
-  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
-- Core and first-party template source lives under
-  `node_modules/@agent-native/core/corpus/core/` and
-  `node_modules/@agent-native/core/corpus/templates/`.
-- Treat those trees as read-only references. Prefer `agent-native eject` so the
-  package manifest selects the complete source closure and rewrites imports.
-  Manual inspection is still useful for deciding whether to configure,
-  compose, eject, or propose a shared seam.
-
-Do not manually guess at sibling dependencies. The ejection manifest owns the
-required file closure and keeps protected contracts on public package imports.
-
-## Preserve The Agent-Native Contract
-
-UI ownership may change; product contracts should not:
-
-- Keep app operations in `defineAction` actions and call them through
-  `useActionQuery`, `useActionMutation`, or another named client helper.
-- Keep navigation, selection, and focused-object state visible through the
-  existing application-state keys.
-- Keep AI work in the shared agent chat instead of adding direct LLM calls.
-- Keep auth, access checks, persistence, chat transport, and agent execution in
-  Core. Do not copy those runtimes into the app.
-- Keep local adapters narrow so package upgrades still improve every surface
-  the app has not intentionally taken ownership of.
-- Keep page, route, and domain code on local UI adapter imports. Never reach
-  around the registered design system with direct Toolkit UI primitive imports.
-
-## App Shapes
-
-- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
-  and domain UI. Use Toolkit features for repeated workspace behavior; eject
-  only the unit being customized.
-- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
-  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
-- **Headless app:** stay action-first while no UI is needed. When adding a UI,
-  use the Chat template as the on-ramp or add Toolkit components without
-  replacing the existing actions.
-- **Workspace:** put one-app overrides in that app. Promote a local component
-  to `packages/shared` only when multiple workspace apps use it.
-
-## After Ejecting
-
-- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
-- Remove unused dependencies and imports from the ejected files.
-- Keep visible text in the app's localization catalogs.
-- Run the manifest verification commands plus the app's formatter, typecheck,
-  and focused tests.
-- Re-check the installed source during future package upgrades; the app-owned
-  ejection does not receive upstream fixes automatically. Use `eject diff` to
-  distinguish recorded output from subsequent local edits.
-
-## Don't
-
-- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
-- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
-- Don't copy Core auth, DB, action, agent-loop, or transport internals.
-- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
-- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
-- Don't fork feature state into a custom view; consume the feature's controller.
-
-## Related Skills
-
-- `agent-native-docs` — version-matched docs and source lookup
-- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
-- `self-modifying-code` — safe app source edits
-- `upgrade-agent-native` — supported package upgrade path
-- `adding-a-feature` — UI/action/instructions/application-state parity