@agent-native/core 0.101.5 → 0.101.7

package/corpus/templates/content/actions/create-content-database.ts

@@ -28,6 +28,10 @@ const createContentDatabaseSchema = z.object({
     .nullish()
     .describe("Parent document for a new database page"),
   title: z.string().optional().describe("Database title"),
+  description: z
+    .string()
+    .optional()
+    .describe("Stable guidance describing what belongs in this database"),
 });
 
 export default defineAction({
@@ -110,6 +114,12 @@ export async function createContentDatabaseRecord(
         .set({ title, updatedAt: now })
         .where(eq(schema.documents.id, documentId));
     }
+    if (args.description !== undefined) {
+      await db
+        .update(schema.documents)
+        .set({ description: args.description.trim(), updatedAt: now })
+        .where(eq(schema.documents.id, documentId));
+    }
   } else {
     title = databaseTitleForPage(title);
     const parentId = args.parentId || null;
@@ -163,6 +173,7 @@ export async function createContentDatabaseRecord(
           parentId,
           title,
           content: "",
+          description: args.description?.trim() ?? "",
           icon: null,
           position: (maxPos?.max ?? -1) + 1,
           isFavorite: 0,

package/corpus/templates/content/actions/create-document.ts

@@ -45,6 +45,12 @@ export default defineAction({
       .describe("Pre-generated document ID (for optimistic UI)"),
     title: z.string().describe("Document title"),
     content: z.string().optional().describe("Markdown content"),
+    description: z
+      .string()
+      .optional()
+      .describe(
+        "Stable guidance describing why this page exists and what belongs in it",
+      ),
     parentId: z.string().nullish().describe("Parent document ID for nesting"),
     icon: z.string().optional().describe("Emoji icon"),
   }),
@@ -78,6 +84,7 @@ export default defineAction({
     const title = args.title;
 
     let content = args.content || "";
+    const description = args.description?.trim() ?? "";
     // Strip leading H1 that duplicates the title
     if (title && content) {
       const h1Match = content.match(/^#\s+(.+?)(\r?\n|$)/);
@@ -154,6 +161,7 @@ export default defineAction({
           parentId,
           title,
           content,
+          description,
           icon,
           position,
           isFavorite: 0,
@@ -202,6 +210,7 @@ export default defineAction({
       parentId: doc.parentId,
       title: doc.title,
       content: doc.content,
+      description: doc.description,
       icon: doc.icon,
       position: doc.position,
       isFavorite: parseDocumentFavorite(doc.isFavorite),

package/corpus/templates/content/actions/create-inline-content-database.ts

@@ -22,10 +22,12 @@ export default defineAction({
   schema: z.object({
     hostDocumentId: z.string().describe("Host page document ID"),
     title: z.string().optional().describe("Database title"),
+    description: z.string().optional().describe("Stable database guidance"),
   }),
   run: async ({
     hostDocumentId,
     title,
+    description,
   }): Promise<CreateInlineDatabaseResponse> => {
     const db = getDb();
     const ownerBlockId = createInlineDatabaseBlockId();
@@ -37,6 +39,7 @@ export default defineAction({
         {
           parentId: hostDocumentId,
           title: databaseTitleForPage(title),
+          description,
         },
         { db: tx },
       );

package/corpus/templates/content/actions/export-content-source.ts

@@ -39,6 +39,7 @@ export default defineAction({
       parentId: doc.parentId,
       title: doc.title,
       content: doc.content,
+      description: doc.description,
       icon: doc.icon,
       position: doc.position,
       isFavorite: parseDocumentFavorite(doc.isFavorite),

package/corpus/templates/content/actions/get-content-database.ts

@@ -11,6 +11,7 @@ import type {
 import {
   CONTENT_DATABASE_MAX_READ_LIMIT,
   getContentDatabaseResponse,
+  getDocumentContextPath,
 } from "./_database-utils.js";
 
 export default defineAction({
@@ -78,6 +79,17 @@ export default defineAction({
       };
     }
 
-    return getContentDatabaseResponse(resolvedDatabaseId, { limit, offset });
+    const response = await getContentDatabaseResponse(resolvedDatabaseId, {
+      limit,
+      offset,
+    });
+    const [document] = await db
+      .select()
+      .from(schema.documents)
+      .where(eq(schema.documents.id, database.documentId));
+    return {
+      ...response,
+      contextPath: document ? await getDocumentContextPath(document) : [],
+    };
   },
 });

package/corpus/templates/content/actions/get-document.ts

@@ -9,6 +9,7 @@ import {
 } from "../server/lib/documents.js";
 import {
   getDatabaseByDocumentId,
+  getDocumentContextPath,
   getDatabaseItemByDocumentId,
   isSoftDeletedDatabaseDocument,
   serializeDatabaseMembership,
@@ -16,6 +17,7 @@ import {
 import { serializeDocumentSource } from "./_document-source.js";
 import {
   getLocalFileDocument,
+  getLocalDocumentContextPath,
   isLocalDocumentId,
   isContentLocalFileMode,
 } from "./_local-file-documents.js";
@@ -45,7 +47,11 @@ export default defineAction({
     if (!args.id) throw new Error("--id is required");
 
     if ((await isContentLocalFileMode()) && isLocalDocumentId(args.id)) {
-      return getLocalFileDocument(args.id);
+      const document = await getLocalFileDocument(args.id);
+      return {
+        ...document,
+        contextPath: await getLocalDocumentContextPath(args.id),
+      };
     }
 
     const access = await resolveAccess("document", args.id);
@@ -76,6 +82,7 @@ export default defineAction({
       parentId: doc.parentId,
       title: doc.title,
       content: doc.content,
+      description: doc.description,
       icon: doc.icon,
       position: doc.position,
       isFavorite: parseDocumentFavorite(doc.isFavorite),
@@ -85,13 +92,16 @@ export default defineAction({
       accessRole: access.role,
       canEdit: canEditRole(access.role),
       canManage: canManageRole(access.role),
-      database: database ? serializeDatabase(database) : undefined,
+      database: database
+        ? serializeDatabase(database, doc.description)
+        : undefined,
       databaseMembership: databaseMembership
         ? serializeDatabaseMembership(databaseMembership)
         : undefined,
       createdAt: doc.createdAt,
       updatedAt: doc.updatedAt,
       properties: await listPropertiesForDocument(doc),
+      contextPath: await getDocumentContextPath(doc),
     };
   },
   link: ({ result }) => {

package/corpus/templates/content/actions/import-content-source.ts

@@ -282,6 +282,9 @@ export default defineAction({
         }
         const titleChanged = file.title !== existing.title;
         const contentChanged = file.content !== existing.content;
+        const descriptionChanged =
+          file.description !== undefined &&
+          file.description !== existing.description;
         const iconChanged =
           file.icon !== undefined && file.icon !== existing.icon;
         const favoriteChanged =
@@ -299,6 +302,7 @@ export default defineAction({
         const anyChange =
           titleChanged ||
           contentChanged ||
+          descriptionChanged ||
           iconChanged ||
           favoriteChanged ||
           discoverabilityChanged ||
@@ -322,6 +326,7 @@ export default defineAction({
           const updates: Record<string, unknown> = { updatedAt: now };
           if (titleChanged) updates.title = file.title;
           if (contentChanged) updates.content = file.content;
+          if (descriptionChanged) updates.description = file.description;
           if (iconChanged) updates.icon = file.icon ?? null;
           if (favoriteChanged) updates.isFavorite = boolToInt(file.isFavorite);
           if (discoverabilityChanged) {
@@ -347,6 +352,7 @@ export default defineAction({
             orgId: currentOrgId,
             parentId: null,
             title: file.title,
+            description: file.description ?? "",
             content: file.content,
             icon: file.icon ?? null,
             position: file.position ?? index,

package/corpus/templates/content/actions/list-documents.ts

@@ -70,6 +70,7 @@ export default defineAction({
         id: schema.documents.id,
         parentId: schema.documents.parentId,
         title: schema.documents.title,
+        description: schema.documents.description,
         contentSnippet: sql<string>`substr(${schema.documents.content}, 1, 400)`,
         contentLength: sql<number>`length(${schema.documents.content})`,
         icon: schema.documents.icon,
@@ -282,6 +283,7 @@ export default defineAction({
           id: d.id,
           parentId: d.parentId,
           title: d.title,
+          description: d.description,
           contentPreview: contentPreview(d.contentSnippet),
           contentLength: Number(d.contentLength) || 0,
           icon: d.icon,
@@ -299,6 +301,7 @@ export default defineAction({
                 id: database.id,
                 documentId: database.documentId,
                 title: database.title,
+                description: d.description,
                 viewConfig: parseDatabaseViewConfig(database.viewConfigJson),
                 createdAt: database.createdAt,
                 updatedAt: database.updatedAt,

package/corpus/templates/content/actions/pull-document.ts

@@ -73,6 +73,7 @@ export default defineAction({
       return {
         id: doc.id,
         title: doc.title,
+        description: doc.description ?? "",
         content: formatDocumentContent(doc.content ?? "", format),
         format,
         deepLink: buildDeepLink({
@@ -104,6 +105,7 @@ export default defineAction({
     return {
       id: doc.id,
       title: doc.title,
+      description: (doc.description as string | null | undefined) ?? "",
       content,
       format,
       deepLink: buildDeepLink({

package/corpus/templates/content/actions/search-documents.ts

@@ -59,6 +59,7 @@ export default defineAction({
           (doc) =>
             !normalizedQuery ||
             doc.title.toLowerCase().includes(normalizedQuery) ||
+            (doc.description ?? "").toLowerCase().includes(normalizedQuery) ||
             doc.content.toLowerCase().includes(normalizedQuery),
         )
         .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
@@ -69,6 +70,7 @@ export default defineAction({
           id: doc.id,
           parentId: doc.parentId,
           title: doc.title,
+          description: doc.description,
           icon: doc.icon,
           snippet: makeSnippet(doc.content, query),
           contentLength: doc.content.length,
@@ -95,6 +97,7 @@ export default defineAction({
         id: schema.documents.id,
         parentId: schema.documents.parentId,
         title: schema.documents.title,
+        description: schema.documents.description,
         icon: schema.documents.icon,
         contentPreview: sql<string>`substr(${schema.documents.content}, 1, 5000)`,
         contentLength: sql<number>`length(${schema.documents.content})`,
@@ -106,7 +109,7 @@ export default defineAction({
         and(
           accessFilter(schema.documents, schema.documentShares),
           documentDiscoveryFilter(),
-          sql`(${schema.documents.title} LIKE ${pattern} ESCAPE '\\' OR ${schema.documents.content} LIKE ${pattern} ESCAPE '\\')`,
+          sql`(${schema.documents.title} LIKE ${pattern} ESCAPE '\\' OR ${schema.documents.description} LIKE ${pattern} ESCAPE '\\' OR ${schema.documents.content} LIKE ${pattern} ESCAPE '\\')`,
         ),
       )
       .orderBy(sql`${schema.documents.updatedAt} DESC`)
@@ -117,6 +120,7 @@ export default defineAction({
         id: doc.id,
         parentId: doc.parentId,
         title: doc.title,
+        description: doc.description,
         icon: doc.icon,
         snippet: makeSnippet(doc.contentPreview, query),
         contentLength: Number(doc.contentLength) || 0,

package/corpus/templates/content/actions/update-document.ts

@@ -152,6 +152,10 @@ export default defineAction({
     id: z.string().optional().describe("Document ID (required)"),
     title: z.string().optional().describe("New title"),
     content: z.string().optional().describe("New markdown content"),
+    description: z
+      .string()
+      .optional()
+      .describe("Stable page guidance; this does not alter page content"),
     icon: z.string().nullable().optional().describe("New emoji icon"),
     isFavorite: z.coerce
       .boolean()
@@ -285,8 +289,15 @@ export default defineAction({
     const favoriteChanged =
       args.isFavorite !== undefined &&
       (args.isFavorite ? 1 : 0) !== (existing.isFavorite ?? 0);
+    const descriptionChanged =
+      args.description !== undefined &&
+      args.description.trim() !== existing.description;
     const anyChange =
-      titleChanged || contentChanged || iconChanged || favoriteChanged;
+      titleChanged ||
+      contentChanged ||
+      iconChanged ||
+      favoriteChanged ||
+      descriptionChanged;
 
     // Snapshot the current state before applying content/title changes.
     // Versions are scoped to the document owner, not the caller — an editor
@@ -338,6 +349,8 @@ export default defineAction({
       };
 
       if (titleChanged) updates.title = args.title;
+      if (args.description !== undefined)
+        updates.description = args.description.trim();
       if (contentChanged) updates.content = content;
       if (iconChanged) updates.icon = args.icon;
       if (favoriteChanged) updates.isFavorite = args.isFavorite ? 1 : 0;
@@ -373,6 +386,7 @@ export default defineAction({
               parentId: current.parentId,
               title: current.title,
               content: current.content,
+              description: current.description,
               icon: current.icon,
               position: current.position,
               isFavorite: parseDocumentFavorite(current.isFavorite),
@@ -449,6 +463,7 @@ export default defineAction({
       parentId: doc.parentId,
       title: doc.title,
       content: doc.content,
+      description: doc.description,
       icon: doc.icon,
       position: doc.position,
       isFavorite: parseDocumentFavorite(doc.isFavorite),

package/corpus/templates/content/actions/view-screen.ts

@@ -34,11 +34,13 @@ import {
   getContentDatabaseResponse,
   getDatabaseByDocumentId,
   getDatabaseItemByDocumentId,
+  getDocumentContextPath,
   serializeDatabaseMembership,
 } from "./_database-utils.js";
 import { serializeDocumentSource } from "./_document-source.js";
 import {
   getLocalFileDocument,
+  getLocalDocumentContextPath,
   isContentLocalFileMode,
   isLocalDocumentId,
   localContentViewScreenSummary,
@@ -675,7 +677,10 @@ export default defineAction({
         ],
       };
       if (nav?.documentId && isLocalDocumentId(nav.documentId)) {
-        screen.document = await getLocalFileDocument(nav.documentId);
+        screen.document = {
+          ...(await getLocalFileDocument(nav.documentId)),
+          contextPath: await getLocalDocumentContextPath(nav.documentId),
+        };
       } else if (nav?.documentId) {
         const access = await resolveAccess("document", nav.documentId);
         if (access) {
@@ -685,6 +690,7 @@ export default defineAction({
             parentId: doc.parentId,
             title: doc.title,
             content: doc.content,
+            description: doc.description,
             icon: doc.icon,
             position: doc.position,
             isFavorite: parseDocumentFavorite(doc.isFavorite),
@@ -693,6 +699,7 @@ export default defineAction({
             source: serializeDocumentSource(doc),
             createdAt: doc.createdAt,
             updatedAt: doc.updatedAt,
+            contextPath: await getDocumentContextPath(doc),
           };
         }
       }
@@ -725,18 +732,22 @@ export default defineAction({
           parentId: doc.parentId,
           title: doc.title,
           content: doc.content,
+          description: doc.description,
           icon: doc.icon,
           position: doc.position,
           isFavorite: parseDocumentFavorite(doc.isFavorite),
           hideFromSearch: parseDocumentHideFromSearch(doc.hideFromSearch),
           visibility: doc.visibility,
-          database: database ? serializeDatabase(database) : undefined,
+          database: database
+            ? serializeDatabase(database, doc.description)
+            : undefined,
           databaseMembership: databaseMembership
             ? serializeDatabaseMembership(databaseMembership)
             : undefined,
           properties: await listPropertiesForDocument(doc),
           createdAt: doc.createdAt,
           updatedAt: doc.updatedAt,
+          contextPath: await getDocumentContextPath(doc),
         };
         if (database) {
           const databaseResponse = await getContentDatabaseResponse(
@@ -774,6 +785,7 @@ export default defineAction({
                   parentId: previewDoc.parentId,
                   title: previewDoc.title,
                   content: previewDoc.content,
+                  description: previewDoc.description,
                   icon: previewDoc.icon,
                   position: previewDoc.position,
                   isFavorite: parseDocumentFavorite(previewDoc.isFavorite),
@@ -786,6 +798,7 @@ export default defineAction({
                   properties: await listPropertiesForDocument(previewDoc),
                   createdAt: previewDoc.createdAt,
                   updatedAt: previewDoc.updatedAt,
+                  contextPath: await getDocumentContextPath(previewDoc),
                 },
               };
             }

package/corpus/templates/content/app/components/editor/DescriptionField.tsx

@@ -0,0 +1,121 @@
+import { useEffect, useRef, useState } from "react";
+
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+
+export function descriptionFieldSavedValue(
+  draft: string,
+  savedDescription: string | null | undefined,
+) {
+  const next = draft.trim();
+  return next === (savedDescription ?? "") ? null : next;
+}
+
+export function descriptionFieldEscapeDraft(
+  savedDescription: string | null | undefined,
+) {
+  return savedDescription ?? "";
+}
+
+/**
+ * Quiet, stable guidance attached to a page or database. This intentionally
+ * renders the owned description only; ancestor context is assembled for agent
+ * reads rather than copied into the surface.
+ */
+export function DescriptionField({
+  description,
+  canEdit,
+  label = "Description",
+  placeholder = "Add a description…",
+  className,
+  onSave,
+}: {
+  description: string | null | undefined;
+  canEdit: boolean;
+  label?: string;
+  placeholder?: string;
+  className?: string;
+  onSave: (description: string) => Promise<unknown> | unknown;
+}) {
+  const [draft, setDraft] = useState(description ?? "");
+  const [editing, setEditing] = useState(false);
+  const skipNextBlurSaveRef = useRef(false);
+  const saveQueueRef = useRef<Promise<void>>(Promise.resolve());
+  const saveRevisionRef = useRef(0);
+  const confirmedDescriptionRef = useRef(description ?? "");
+
+  useEffect(() => {
+    confirmedDescriptionRef.current = description ?? "";
+  }, [description]);
+
+  useEffect(() => {
+    if (!editing) setDraft(description ?? "");
+  }, [description, editing]);
+
+  const save = async () => {
+    const next = descriptionFieldSavedValue(draft, description);
+    if (next === null) return;
+
+    const revision = ++saveRevisionRef.current;
+    const request = saveQueueRef.current.then(() => onSave(next));
+    saveQueueRef.current = request.then(
+      () => undefined,
+      () => undefined,
+    );
+
+    try {
+      await request;
+      confirmedDescriptionRef.current = next;
+    } catch {
+      if (saveRevisionRef.current === revision) {
+        setDraft(confirmedDescriptionRef.current);
+      }
+    }
+  };
+
+  if (!canEdit && !description) return null;
+
+  if (!canEdit) {
+    return (
+      <p
+        className={cn(
+          "mt-2 text-sm leading-6 text-muted-foreground",
+          className,
+        )}
+      >
+        {description}
+      </p>
+    );
+  }
+
+  return (
+    <Textarea
+      aria-label={label}
+      rows={editing || draft ? 2 : 1}
+      value={draft}
+      placeholder={placeholder}
+      onFocus={() => setEditing(true)}
+      onChange={(event) => setDraft(event.target.value)}
+      onBlur={() => {
+        setEditing(false);
+        if (skipNextBlurSaveRef.current) {
+          skipNextBlurSaveRef.current = false;
+          return;
+        }
+        void save();
+      }}
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          skipNextBlurSaveRef.current = true;
+          setDraft(descriptionFieldEscapeDraft(description));
+          event.currentTarget.blur();
+        }
+      }}
+      className={cn(
+        "mt-2 block w-full resize-none overflow-hidden rounded border-0 bg-transparent px-0 py-0 text-sm leading-6 text-muted-foreground outline-none placeholder:text-muted-foreground/45 hover:bg-muted/30 focus:bg-muted/30 focus:px-1 focus:outline-none focus:ring-1 focus:ring-ring",
+        className,
+      )}
+    />
+  );
+}

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -61,6 +61,7 @@ import {
 import { BuilderBodySyncingNotice } from "./BuilderBodySyncingNotice";
 import type { CommentTextAnchor } from "./comment-anchors";
 import { CommentsSidebar } from "./CommentsSidebar";
+import { DescriptionField } from "./DescriptionField";
 import { DocumentBlockFields } from "./DocumentBlockFields";
 import { DocumentDatabase } from "./DocumentDatabase";
 import { DocumentEditorSkeleton } from "./DocumentEditorSkeleton";
@@ -629,6 +630,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       updates: {
         title?: string;
         content?: string;
+        description?: string;
         icon?: string | null;
       },
       options: DocumentSaveOptions = {},
@@ -645,6 +647,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
         ...document,
         title: updates.title ?? localTitleRef.current,
         content: updates.content ?? localContentRef.current,
+        description: updates.description ?? document.description,
         icon: updates.icon !== undefined ? updates.icon : document.icon,
         updatedAt: nextSavedAt,
         source: localSource,
@@ -1431,6 +1434,17 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                       isDatabasePage ? "text-3xl" : "text-3xl md:text-4xl",
                     )}
                   />
+                  {!document.database ? (
+                    <DescriptionField
+                      description={document.description}
+                      canEdit={editorCanEdit}
+                      label={t("editor.properties.description")}
+                      placeholder={t("editor.properties.addPageDescription")}
+                      onSave={(description) =>
+                        persistDocumentUpdates({ description })
+                      }
+                    />
+                  ) : null}
                   {document.databaseMembership && !isLocalFileDocument ? (
                     <DocumentProperties
                       documentId={documentId}