@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/content/AGENTS.md

@@ -1,11 +1,23 @@
 # Documents — Agent Guide
 
-Documents is an agent-native editor for docs, comments, media blocks, sharing,
-and Notion-connected content. The agent edits documents through actions and
-application state shared with the UI.
+Documents is an agent-native editor for docs, comments, media blocks, databases,
+sharing, and Notion-connected content; the agent and the UI share the same
+actions and application state.
 
-Detailed document editing, Notion, storage, and UI rules live in
-`.agents/skills/`.
+## Skills
+
+Read the relevant skill before deeper work:
+
+- `content` — Markdown/MDX authoring, local folder sources, databases, intake
+  forms, and Slack/A2A artifact replies.
+- `document-editing` — document and comment actions, screen context and IDs,
+  common tasks, the data model, and the databases reference.
+- `notion-integration` — connected Notion workflows and the raw Notion provider
+  API path.
+- `creative-context` — cross-app source reuse, pinned packs, provenance, and
+  context opt-out.
+- `storing-data`, `real-time-sync`, `security`, `actions`, `frontend-design`,
+  and `shadcn-ui` for framework work.
 
 Before building common workspace or agent UI, read `agent-native-toolkit` to
 inventory existing public kits and installed package seams. Use
@@ -14,145 +26,65 @@ ladder.
 
 ## Core Rules
 
-- Store large file/blob payloads in configured file/blob storage, not SQL: no
-  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
-  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
-  or `resources`; persist URLs, ids, or handles instead.
-- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for documents, blocks, comments, media, sharing, navigation, and
   Notion integration. Do not mutate document rows directly unless a skill says to
-  and access checks are preserved.
-- Notion workspace access is per-user OAuth only. Never read `NOTION_API_KEY`
-  from `process.env`, never save a user-entered Notion token through
-  `/_agent-native/env-vars`, and require editor access for routes that pull or
-  push Notion content.
-- Treat Notion workflow actions as shortcuts, not capability limits. When the
-  exact Notion endpoint/filter/pagination/API version matters, use
-  `provider-api-catalog`, `provider-api-docs`, and `provider-api-request`
-  against the real Notion API. The provider API resolves auth from the user's
-  Notion OAuth connection, never from `NOTION_API_KEY`. For large scans, stage
-  results with `stageAs` and analyze them with `query-staged-dataset`.
-- Preserve user-authored content. Prefer targeted edits over wholesale rewrites
-  unless requested.
-- Screen context is auto-included as a `<current-screen>` block on every
-  message — check it before acting instead of calling `view-screen` by
-  default. Call `view-screen` explicitly only when that snapshot is truncated
-  or doesn't yet reflect something that changed earlier in the same turn (for
-  example, right after `create-document` or `navigate`).
-- Keep public/exported content server-renderable where relevant.
+  and access checks are preserved. Never use `curl`, raw HTTP requests, or
+  `db-exec` with raw SQL for document operations.
 - The editor uses live Yjs collaboration — raw SQL writes to `documents` won't
   appear in an open editor. Always use `edit-document` or `update-document`,
   and prefer `edit-document` for small changes (it sends only the changed
   text and syncs live via CRDT instead of regenerating the whole document).
+- Preserve user-authored content. Prefer targeted edits over wholesale rewrites
+  unless requested.
 - `create-document`, `update-document`, and `delete-document` already signal
   a UI refresh; only call `refresh-list` directly if you mutate documents
   another way and the UI doesn't update.
+- Screen context is auto-included as a `<current-screen>` block on every
+  message — check it before acting instead of calling `view-screen` by default.
+  IDs for edits always come from `<current-screen>` or a prior action result,
+  never guessed.
+- Documents are **private by default**; use `share-resource` /
+  `set-resource-visibility` (`resourceType document`) to change access. Keep
+  public/exported content server-renderable where relevant.
+- Notion workspace access is per-user OAuth only: never read `NOTION_API_KEY`
+  from `process.env`, never save a user-entered token, and require editor access
+  to pull or push. Notion actions are shortcuts, not capability limits — see
+  `notion-integration` for the `provider-api-*` path when an exact endpoint,
+  filter, pagination mode, or API version matters.
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
+- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 
 ## Application State
 
-- Before generation, follow the creative-context reuse ladder in
-  `.agents/skills/creative-context/SKILL.md`: explicit request and current
-  document first, then a pinned/current pack, then narrow library search.
-  Respect `creative-context.contextMode: "off"` without silently restoring a
-  pack.
-- To submit a document to a governed Creative Context, use the Context tab or
-  `manage-context-membership`; the app flushes live collaboration and captures
-  one immutable Markdown version. Reuse only its opaque native clone reference.
-  Use `operation="submit-latest"` with a Library membership id when its native
-  update status reports `update-available`.
-
-- `navigation` exposes document, selected block, comment, media, and Notion view
-  context.
-- `navigate` moves the UI to documents, comments, media, and settings surfaces.
+- `navigation` — `{ "view": "list" | "editor", "documentId": "abc123" }`, plus
+  selected block, comment, media, and Notion view context. `list` is the
+  document tree; `editor` is one open document. **Do NOT write to
+  `navigation`** — it is overwritten by the UI. Use `navigate` to control the UI.
+- `creative-context` — `contextMode`, `selectedContextId`, `currentPackId`,
+  `pinnedPackId`. Follow the `creative-context` reuse ladder before generating,
+  and respect `contextMode: "off"` without silently restoring a pack.
 - Use actions for full document content and comment context.
 
-## Skills
-
-- `creative-context` for cross-app source reuse, pinned packs, provenance, and
-  context opt-out.
-
-Read the relevant skill before deeper work:
-
-- `document-editing` for structured document updates.
-- `notion-integration` for connected Notion workflows.
-- `storing-data`, `real-time-sync`, `security`, `actions`, `frontend-design`,
-  and `shadcn-ui` for framework work.
-
-## Navigation State
-
-```json
-{
-  "view": "editor",
-  "documentId": "abc123"
-}
-```
-
-Views: `list` (document tree), `editor` (viewing/editing a document).
-
-**Do NOT write to `navigation`** — it is overwritten by the UI. Use `navigate` to control the UI.
-
 ## Actions
 
-In dev, call actions with `pnpm action <name>`; in production, call native
-tools. Never use `curl`, raw HTTP requests, or `db-exec` with raw SQL for
-document operations. `.env` is loaded automatically — never manually set
-`DATABASE_URL` or other env vars.
-
-`view-screen`, `navigate`, and `refresh-list` handle context and UI control.
-`list-documents`, `search-documents`, `get-document`, `pull-document`,
-`create-document`, `edit-document`, `update-document`, and `delete-document`
-cover the core document workflow. Every action carries its own schema. Other
-app-specific tools, including `remove-local-file-source`, are registered; use
-`tool-search` instead of scanning a table here.
-
-### Cross-App A2A / Slack Artifact Rule
-
-Create or update the document through the normal action path (never a bespoke route) so the artifact stays visible and shareable. When a request arrives from Slack, Dispatch, or another app via A2A, the caller cannot see Content's local UI or navigation state: reply with the concrete document ID and URL/path only after the action succeeds. Use `/page/<id>` for private app documents (or `/p/<id>` only for documents you explicitly made public). Never say a document is ready without including the exact ID or URL/path returned by the action.
-
-### Deeper Behavior (Read On Demand)
-
-- `references/document-behavior.md` (`document-editing` skill) — description
-  ownership, `pull-document`'s collab-flush handshake vs `get-document`,
-  versions, image blocks, sharing/visibility (`/page/<id>` vs `/p/<id>`,
-  discoverability, the read-only public chat).
-- `references/local-file-mode.md` (`content` skill) — local folder sources,
-  Builder Symbol/source-component preservation, local MDX components.
-- `notion-integration` skill — connecting, sync, conflicts, the read-only
-  database-source pilot.
-- `document-editing` skill's Comments section — inline anchor-tracked
-  threads, @mentions, resolve/reopen.
-
-Documents are **private by default**; use `share-resource` /
-`set-resource-visibility` (`resourceType document`) to change access.
-
-## Common Tasks
-
-| User request              | What to do                                                                        |
-| ------------------------- | --------------------------------------------------------------------------------- |
-| "What am I looking at?"   | Answer from `<current-screen>` (call `view-screen` only if truncated)             |
-| "Create a page about X"   | `create-document --title "X" --content "# X\n\n..."`                              |
-| "Fix a typo / small edit" | ID from `<current-screen>`, `edit-document --id ... --find "old" --replace "new"` |
-| "Delete this page"        | ID from `<current-screen>`, `delete-document --id ...`                            |
-
-IDs for edits always come from `<current-screen>` or a prior action result —
-never guessed.
-
-## Data Model
-
-Documents live in the SQL `documents` table via Drizzle; the framework
-injects the live column schema separately, so this section only covers
-semantics the schema can't convey:
-
-- `document_shares` holds per-user/per-org grants with a `viewer`, `editor`,
-  or `admin` role.
-- `document_versions`, `document_comments`, and `document_sync_links` all
-  carry `owner_email` so a workspace can upgrade from local mode to a real
-  account without losing history, comments, or Notion links.
-- A database is a normal document (`content_databases` +
-  `document_property_definitions`) whose rows are also documents, linked
-  through `content_database_items`. Row pages are omitted from the ordinary
-  sidebar tree — they're reached through the database view.
-
-See `references/databases.md` in the `document-editing` skill for the full
-database behavior reference: property types, Blocks fields, and every view
-type (table, list, gallery, board, calendar, timeline, form).
+| Action | Purpose |
+| --- | --- |
+| `view-screen` | Re-read the current screen when `<current-screen>` is stale |
+| `navigate` | Move the UI to a document, comments, media, or settings |
+| `refresh-list` | Repaint the sidebar after an out-of-band mutation |
+| `list-documents` | Document metadata tree, without bodies |
+| `search-documents` | Title and content search with snippets |
+| `get-document` | One document with full content |
+| `pull-document` | Flush live collab state, then read (external edits) |
+| `create-document` | Create a page, optionally under a parent |
+| `edit-document` | Find/replace edit — preferred for small changes |
+| `update-document` | Full rewrite of title, content, or description |
+| `delete-document` | Move a page and its children to Trash |
+
+Every action carries its own schema, and the rest of the app-specific surface
+(comments, sharing, databases, Notion, local file sources such as
+`remove-local-file-source`) is registered too — use `tool-search` instead of
+scanning a table here.

package/corpus/templates/content/app/routes/_app.tsx

@@ -1,6 +1,6 @@
 import { Outlet } from "react-router";
 
-import { AppLayout } from "@/components/layout/AppLayout";
+import { Layout } from "@/components/layout/Layout";
 import { messagesByLocale } from "@/i18n-data";
 
 export function meta() {
@@ -15,12 +15,12 @@ export function meta() {
   ];
 }
 
-// Pathless layout route — wraps all protected routes with AppLayout so the
+// Pathless layout route — wraps all protected routes with Layout so the
 // agent sidebar and document tree persist across client-side navigations.
 export default function AppLayoutRoute() {
   return (
-    <AppLayout>
+    <Layout>
       <Outlet />
-    </AppLayout>
+    </Layout>
   );
 }

package/corpus/templates/content/server/routes/api/notion/callback.get.ts

@@ -7,17 +7,16 @@
  * verbatim is an open-redirect primitive: an attacker can craft a state
  * blob that points the post-callback redirect at `//evil.example/phish`.
  *
- * To close that hole without depending on the lib's internal helpers (the
- * lib is in concurrent flight elsewhere), this handler:
+ * To close that hole, this handler:
  *
  *   1. Parses the state JSON exactly the way the lib does.
  *   2. Verifies an HMAC signature in `state.sig` against
  *      `BETTER_AUTH_SECRET` (or `AUTH_SECRET`). If absent or wrong, we
  *      ignore the carried `redirectPath` entirely.
  *   3. Even when the HMAC verifies, the resulting `redirectPath` is run
- *      through a same-origin path-only check (modeled on
- *      `safeReturnPath`) before being passed to `sendRedirect` — so a
- *      protocol-relative URL like `//host/evil` falls back to `/`.
+ *      through the framework's shared `safeReturnPath` before being passed
+ *      to `sendRedirect` — so a protocol-relative URL like `//host/evil`
+ *      falls back to `/`.
  *
  * Separately, before ANY token exchange/save happens, this handler verifies
  * the `notion_oauth_state` HttpOnly cookie set by `buildNotionAuthUrl`
@@ -31,6 +30,7 @@
 import crypto from "node:crypto";
 
 import { OAuthAccountOwnedByOtherUserError } from "@agent-native/core/oauth-tokens";
+import { safeReturnPath } from "@agent-native/core/server";
 import {
   defineEventHandler,
   deleteCookie,
@@ -103,24 +103,6 @@ function verifyStateSignature(state: Record<string, any>): {
   return { ok: true, redirectPath: claimed };
 }
 
-/**
- * Mirror of `safeReturnPath` from `@agent-native/core/server` — duplicated
- * here so this fix doesn't depend on a yet-unreleased core export. Rejects
- * absolute URLs, protocol-relative `//host` URLs, backslash bypasses, and
- * data:/javascript: schemes by parsing against a sentinel origin.
- */
-function safeReturnPathLocal(raw: string | null | undefined): string {
-  if (!raw) return "/";
-  if (/[\x00-\x1f]/.test(raw)) return "/";
-  try {
-    const parsed = new URL(raw, "http://safe-base.invalid");
-    if (parsed.origin !== "http://safe-base.invalid") return "/";
-    return parsed.pathname + parsed.search + parsed.hash;
-  } catch {
-    return "/";
-  }
-}
-
 export default defineEventHandler(async (event) => {
   const query = getQuery(event);
   const code = query.code as string | undefined;
@@ -141,7 +123,7 @@ export default defineEventHandler(async (event) => {
   // target regardless of how the rest of the handler exits.
   const state = decodeStateJson(stateParam);
   const verified = verifyStateSignature(state);
-  const target = verified.ok ? safeReturnPathLocal(verified.redirectPath) : "/";
+  const target = verified.ok ? safeReturnPath(verified.redirectPath) : "/";
 
   // CSRF binding: the nonce in `state.n` must match the HttpOnly cookie set
   // by buildNotionAuthUrl for the session that started this flow. Reject

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,177 @@
+---
+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`