@agent-native/core 0.114.15 → 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/app/components/editor/database/DatabaseView.tsx

@@ -4143,25 +4143,6 @@ function DatabaseItemPreview({
             draftVersionsRef.current.set(documentId, null);
           else if (result.draft) {
             draftVersionsRef.current.set(documentId, result.draft.version);
-            if (
-              previewDraftNeedsConflict({
-                returnedDraft: result.draft,
-                pending: controller.pending,
-              })
-            ) {
-              controller.notifyDraftConflict({
-                lastSaved: snapshot.lastSaved,
-                pending: {
-                  title: result.draft.title,
-                  content: result.draft.content,
-                  loadedUpdatedAt:
-                    result.draft.baseDocumentUpdatedAt ?? undefined,
-                  loadedContentWasEmpty:
-                    result.draft.loadedContentWasEmpty === 1,
-                },
-                deferredReason: "conflict",
-              });
-            }
           } else {
             // Another tab already removed the row. Treat the stale delete as
             // converged instead of retaining a version that can never match.
@@ -4186,24 +4167,6 @@ function DatabaseItemPreview({
           draftVersionsRef.current.set(documentId, result.draft.version);
         } else if (result.draft) {
           draftVersionsRef.current.set(documentId, result.draft.version);
-          if (
-            previewDraftNeedsConflict({
-              returnedDraft: result.draft,
-              pending: controller.pending,
-            })
-          ) {
-            controller.notifyDraftConflict({
-              lastSaved: snapshot.lastSaved,
-              pending: {
-                title: result.draft.title,
-                content: result.draft.content,
-                loadedUpdatedAt:
-                  result.draft.baseDocumentUpdatedAt ?? undefined,
-                loadedContentWasEmpty: result.draft.loadedContentWasEmpty === 1,
-              },
-              deferredReason: "conflict",
-            });
-          }
         } else {
           // A competing tab deleted the version we tried to update. Reset to
           // create mode and enqueue the latest pending payload once; keeping
@@ -4298,7 +4261,13 @@ function DatabaseItemPreview({
                 );
                 return;
               }
-              resolve(undefined);
+              resolve({
+                outcome: "saved" as const,
+                loadedUpdatedAt: result.updatedAt,
+                loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
+                  result.content,
+                ),
+              });
             },
             onError: reject,
           },
@@ -4410,6 +4379,8 @@ function DatabaseItemPreview({
       }
       return;
     }
+    const previouslyExpectedVersion =
+      draftVersionsRef.current.get(documentId) ?? null;
     draftVersionsRef.current.set(documentId, draft.version);
     const controller = peekPreviewDocumentSaveController(documentId);
     if (!controller) return;
@@ -4431,8 +4402,19 @@ function DatabaseItemPreview({
           ? draft.deferredReason
           : null,
     } as const;
+    // A poll tick simply confirming a version this client's own debounced
+    // write already advanced the ref to is not an external change — it is
+    // this client's typing racing ahead of its own last round trip. Comparing
+    // that echo against the still-live `pending` would flag a conflict on
+    // almost every keystroke. Only treat the draft as having moved out from
+    // under the user when its version is newer than what this client itself
+    // last recorded.
+    const draftAdvancedExternally =
+      previouslyExpectedVersion !== null &&
+      draft.version > previouslyExpectedVersion;
     if (controllerDirty) {
       if (
+        draftAdvancedExternally &&
         previewDraftNeedsConflict({
           returnedDraft: draft,
           pending: controller.pending,

package/corpus/templates/content/app/components/editor/previewDocumentSaveController.ts

@@ -67,6 +67,19 @@ export interface PreviewDocumentSaveDeferred {
   conflictSnapshot?: PreviewDocumentDraftSnapshot;
 }
 
+/**
+ * A successful save can report the server's fresh `updatedAt`/emptiness back
+ * to the controller so its baseline stops looking stale. Without this, a
+ * baseline seeded as empty (a brand-new page) stays flagged empty forever, so
+ * a later poll of content the user just saved themselves gets mistaken for a
+ * non-empty body arriving externally over an empty one.
+ */
+export interface PreviewDocumentSaveSuccess {
+  outcome: "saved";
+  loadedUpdatedAt?: string;
+  loadedContentWasEmpty?: boolean;
+}
+
 export interface PreviewDocumentSaveAdapter {
   save: (
     documentId: string,
@@ -151,6 +164,18 @@ function payloadsEqual(a: PreviewDocumentPayload, b: PreviewDocumentPayload) {
   return a.title === b.title && a.content === b.content;
 }
 
+function asSaveSuccess(result: unknown): PreviewDocumentSaveSuccess | null {
+  if (
+    result &&
+    typeof result === "object" &&
+    "outcome" in result &&
+    (result as { outcome?: unknown }).outcome === "saved"
+  ) {
+    return result as PreviewDocumentSaveSuccess;
+  }
+  return null;
+}
+
 export function createPreviewDocumentSaveController(
   args: PreviewDocumentSaveAdapter & {
     /**
@@ -230,7 +255,21 @@ export function createPreviewDocumentSaveController(
           }
           return;
         }
-        lastSaved = attempted;
+        // Adopt the server's fresh metadata (if the adapter reported it) into
+        // the confirmed baseline. Otherwise `loadedUpdatedAt`/
+        // `loadedContentWasEmpty` would keep carrying whatever was true when
+        // the controller was created/last marked — e.g. "empty" for a
+        // brand-new page — forever, even after real content has been saved.
+        const success = asSaveSuccess(result);
+        lastSaved = {
+          ...attempted,
+          ...(success?.loadedUpdatedAt !== undefined
+            ? { loadedUpdatedAt: success.loadedUpdatedAt }
+            : {}),
+          ...(success?.loadedContentWasEmpty !== undefined
+            ? { loadedContentWasEmpty: success.loadedContentWasEmpty }
+            : {}),
+        };
         hasSavedLocally = true;
         deferredReason = null;
         inFlight = null;

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`