@agent-native/core 0.101.6 → 0.101.7

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}