@agent-native/core 0.101.6 → 0.101.7

package/corpus/templates/content/AGENTS.md

@@ -102,19 +102,19 @@ cd templates/content && pnpm action <name> [args]
 | `push-builder-doc`                          | `--files <json> [--path <file.builder.mdx>] [--dryRun true\|false]`                                                                                                                                | Guarded Builder autosave PATCH for the safe Builder test model; never publishes                                                                                                   |
 | `navigate`                                  | `--path <path>` or `--documentId <id>` or `--databaseId <id>`                                                                                                                                      | Open a route, document page, or database page in the UI                                                                                                                           |
 | `search-documents`                          | `--query <text> [--format json]`                                                                                                                                                                   | Search by title/content and return snippets                                                                                                                                       |
-| `get-document`                              | `--id <id> [--format json]`                                                                                                                                                                        | Get a single document with content                                                                                                                                                |
+| `get-document`                              | `--id <id> [--format json]`                                                                                                                                                                        | Get a document with content, stable description, properties, and computed ancestry context                                                                                        |
 | `pull-document`                             | `--id <id> [--format markdown\|text]`                                                                                                                                                              | Collab-aware "ingest the final" read                                                                                                                                              |
-| `create-document`                           | `--title <text> [--content] [--parentId] [--icon]`                                                                                                                                                 | Create a new document                                                                                                                                                             |
+| `create-document`                           | `--title <text> [--content] [--description] [--parentId] [--icon]`                                                                                                                                 | Create a document with optional stable guidance about why it exists and what belongs there                                                                                        |
 | `edit-document`                             | `--id <id> --find <text> --replace <text>`                                                                                                                                                         | Surgical text edit (preferred for modifications)                                                                                                                                  |
 | `edit-document`                             | `--id <id> --edits <json>`                                                                                                                                                                         | Batch surgical text edits                                                                                                                                                         |
-| `update-document`                           | `--id <id> [--title] [--content] [--icon]`                                                                                                                                                         | Full rewrite of document fields                                                                                                                                                   |
+| `update-document`                           | `--id <id> [--title] [--content] [--description] [--icon]`                                                                                                                                         | Update document fields; descriptions are stable guidance, not summaries of current content                                                                                        |
 | `share-local-file-document`                 | `--id <local-file-document-id>`                                                                                                                                                                    | Create or refresh a DB-backed shareable copy of a local file document                                                                                                             |
 | `remove-local-file-source`                  | `[--sourceRootPath <path>]`                                                                                                                                                                        | Unlink local-file sources from Content without deleting local Markdown/MDX files                                                                                                  |
 | `list-local-component-files`                |                                                                                                                                                                                                    | List registered local MDX component source files                                                                                                                                  |
 | `write-local-component-file`                | `--workspaceId <id> --path <relative-component-path> --content <source>`                                                                                                                           | Create or update a file in a registered local `components/` folder                                                                                                                |
-| `create-content-database`                   | `[--documentId <id>] [--parentId <id>] [--title <text>]`                                                                                                                                           | Create a database page or convert an existing page into a database                                                                                                                |
-| `create-inline-content-database`            | `--hostDocumentId <id> [--title <text>]`                                                                                                                                                           | Create a database owned by an inline database block in the host document                                                                                                          |
-| `get-content-database`                      | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Get a database table with property schema and item pages                                                                                                                          |
+| `create-content-database`                   | `[--documentId <id>] [--parentId <id>] [--title <text>] [--description <text>]`                                                                                                                    | Create a described database page or convert an existing page into a database                                                                                                      |
+| `create-inline-content-database`            | `--hostDocumentId <id> [--title <text>] [--description <text>]`                                                                                                                                    | Create a described database owned by an inline database block in the host document                                                                                                |
+| `get-content-database`                      | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Get a database with its description, property/option schema guidance, item pages, and computed ancestry context                                                                   |
 | `list-trashed-content-databases`            |                                                                                                                                                                                                    | List soft-deleted databases visible in the sidebar Trash surface                                                                                                                  |
 | `restore-content-database`                  | `--databaseId <id>`                                                                                                                                                                                | Restore a soft-deleted database from the sidebar Trash surface                                                                                                                    |
 | `get-content-database-source`               | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Inspect local/no-source or source-backed status, mappings, row identity, freshness, and change sets                                                                               |
@@ -138,7 +138,7 @@ cd templates/content && pnpm action <name> [args]
 | `move-database-item`                        | `--itemId <id>` or `--documentId <id> --position <number>`                                                                                                                                         | Move a database row page to a new zero-based table position                                                                                                                       |
 | `update-content-database-view`              | `--databaseId <id> --viewConfig <json>`                                                                                                                                                            | Persist database views, sorts, filters, hidden properties, and view settings                                                                                                      |
 | `list-document-properties`                  | `--documentId <id> [--format json]`                                                                                                                                                                | List Notion-style property definitions and values for a document                                                                                                                  |
-| `configure-document-property`               | `--documentId <id> [--id <propertyId>] --name <name> --type <type> [--visibility always_show\|hide_when_empty\|always_hide]`                                                                       | Create or update a property definition                                                                                                                                            |
+| `configure-document-property`               | `--documentId <id> [--id <propertyId>] --name <name> --type <type> [--description <text>] [--visibility always_show\|hide_when_empty\|always_hide] [--options <json>]`                             | Create or update a property definition and its option-level guidance                                                                                                              |
 | `duplicate-document-property`               | `--documentId <id> --propertyId <propertyId>`                                                                                                                                                      | Duplicate a property definition and its stored values                                                                                                                             |
 | `delete-document-property`                  | `--documentId <id> --propertyId <propertyId>`                                                                                                                                                      | Delete a property definition and its stored values                                                                                                                                |
 | `set-document-property`                     | `--documentId <id> --propertyId <propertyId> --value <json>`                                                                                                                                       | Set a document property value (for a `blocks` field, the value is its markdown content)                                                                                           |
@@ -151,6 +151,27 @@ Database views follow Notion-style tab labels. When creating or duplicating
 views in `viewConfig`, use unique default names (`Table 2`, `SEO copy 2`, etc.)
 instead of appending several tabs with the same label.
 
+### Self-Documenting Descriptions
+
+Descriptions are stable semantic guidance, not generated summaries of current
+content. Preserve this distinction when reading or writing them:
+
+- A page description explains why the page exists and what belongs there.
+- A database description explains the collection's purpose and inclusion
+  boundary. Inline and full-page views of one database share the same
+  description.
+- A property description explains what the field means and what value belongs
+  there.
+- A select, status, or multi-select option description explains when to choose
+  that option.
+
+Descriptions are owned; context is inherited. Never copy an ancestor's prose
+into a child description. Focused reads expose a root-to-parent `contextPath`
+so the agent can use ancestor guidance without creating stale duplicates. Read
+the returned descriptions before placing content or setting property values.
+Update a description only when the object's meaning changes, not whenever its
+current content changes.
+
 **`pull-document` is the collab-aware "ingest the final" read** — prefer it over
 `get-document` for external ingest (another app, an external coding agent over
 MCP/A2A, an A2A peer). `get-document` returns whatever is in the
@@ -388,6 +409,7 @@ Public documents are reachable at `/p/<id>` once visibility is `public`. Anyone
 | ------------------------------ | ------------------------------------------------------------------------------ |
 | "What am I looking at?"        | `view-screen`                                                                  |
 | "Create a page about X"        | `create-document --title "X" --content "# X\n\n..."`                           |
+| "Explain what belongs here"    | `view-screen` to get ID, `update-document --id ... --description "..."`        |
 | "Find my meeting notes"        | `search-documents --query "meeting notes"`                                     |
 | "Update the title of this doc" | `view-screen` to get ID, `update-document --id ... --title "New"`              |
 | "Fix a typo / small edit"      | `view-screen` to get ID, `edit-document --id ... --find "old" --replace "new"` |

package/corpus/templates/content/actions/_database-source-utils.ts

@@ -49,6 +49,7 @@ import {
   parsePropertyOptions,
   serializePropertyOptions,
   serializePropertyValue,
+  type DocumentPropertyOption,
   type DocumentPropertyOptionColor,
 } from "../shared/properties.js";
 import { sanitizeNormalizationFormula } from "../shared/properties.js";
@@ -5193,6 +5194,34 @@ const SOURCE_OPTION_PALETTE: DocumentPropertyOptionColor[] = [
   "red",
 ];
 
+export function sourcePropertyOptionsForSources(
+  sources: Array<{ id: string; sourceName: string }>,
+  priorOptions: DocumentPropertyOption[],
+) {
+  const priorById = new Map(priorOptions.map((option) => [option.id, option]));
+  const retainDescription = (id: string) => {
+    const description = priorById.get(id)?.description;
+    return description ? { description } : {};
+  };
+  return [
+    ...sources.map((source, index) => ({
+      id: source.id,
+      name: source.sourceName,
+      color:
+        priorById.get(source.id)?.color ??
+        SOURCE_OPTION_PALETTE[index % SOURCE_OPTION_PALETTE.length],
+      ...retainDescription(source.id),
+    })),
+    {
+      id: SOURCE_LOCAL_OPTION_ID,
+      name: "Local",
+      color: (priorById.get(SOURCE_LOCAL_OPTION_ID)?.color ??
+        "gray") as DocumentPropertyOptionColor,
+      ...retainDescription(SOURCE_LOCAL_OPTION_ID),
+    },
+  ];
+}
+
 /**
  * Ensure a "Source" select property exists tagging each row with the collection
  * it belongs to, and (re)set every item's value. Rows with no source binding are
@@ -5233,22 +5262,7 @@ export async function ensureDatabaseSourceProperty(args: {
   // that can't collide with a UUID source id). Resolving a row's tag back to a
   // source is then pure id matching — no source-name hop — so duplicate display
   // names or a collection literally named "Local" can never misroute a row.
-  const priorById = new Map(priorOptions.map((option) => [option.id, option]));
-  const options = [
-    ...sources.map((source, index) => ({
-      id: source.id,
-      name: source.sourceName,
-      color:
-        priorById.get(source.id)?.color ??
-        SOURCE_OPTION_PALETTE[index % SOURCE_OPTION_PALETTE.length],
-    })),
-    {
-      id: SOURCE_LOCAL_OPTION_ID,
-      name: "Local",
-      color: (priorById.get(SOURCE_LOCAL_OPTION_ID)?.color ??
-        "gray") as DocumentPropertyOptionColor,
-    },
-  ];
+  const options = sourcePropertyOptionsForSources(sources, priorOptions);
   const optionsJson = serializePropertyOptions({ options });
 
   let propertyId: string;

package/corpus/templates/content/actions/_database-utils.ts

@@ -1,6 +1,7 @@
 import { and, asc, eq, inArray, isNull, sql } from "drizzle-orm";
 
 import { getDb, schema } from "../server/db/index.js";
+import { getDocumentContextPath } from "../server/lib/document-context.js";
 import {
   parseDocumentFavorite,
   parseDocumentHideFromSearch,
@@ -20,6 +21,7 @@ import {
   listPropertiesForDatabase,
   serializeDatabase,
 } from "./_property-utils.js";
+export { getDocumentContextPath };
 
 export const CONTENT_DATABASE_MAX_READ_LIMIT = 5_000;
 
@@ -131,6 +133,7 @@ function serializeDocument(
     parentId: doc.parentId,
     title: doc.title,
     content: options.includeContent === true ? doc.content : "",
+    description: doc.description,
     icon: doc.icon,
     position: doc.position,
     isFavorite: parseDocumentFavorite(doc.isFavorite),
@@ -160,6 +163,14 @@ export async function getContentDatabaseResponse(
   if (!database || database.deletedAt) {
     throw new Error(`Database "${databaseId}" not found`);
   }
+  const [databaseDocument] = await db
+    .select({
+      id: schema.documents.id,
+      parentId: schema.documents.parentId,
+      description: schema.documents.description,
+    })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, database.documentId));
 
   // PURE read: the primary "Content" Blocks field is seeded at create time and
   // by the one-time startup repair — never here. Reading a database (including a
@@ -272,7 +283,10 @@ export async function getContentDatabaseResponse(
   const itemsWithOverlay = applyFederatedOverlayValues(federatedItems);
 
   return {
-    database: serializeDatabase(database),
+    database: serializeDatabase(database, databaseDocument?.description ?? ""),
+    contextPath: databaseDocument
+      ? await getDocumentContextPath(databaseDocument)
+      : [],
     properties: await listPropertiesForDatabase(databaseId),
     items: itemsWithOverlay,
     source: pagedPrimary,

package/corpus/templates/content/actions/_local-file-documents.ts

@@ -154,6 +154,7 @@ function documentFromFolder(folderPath: string, position: number): Document {
     parentId: folderParentId(folderPath),
     title: titleFromSegment(basename(folderPath)),
     content: "",
+    description: "",
     icon: null,
     position,
     isFavorite: false,
@@ -189,6 +190,7 @@ function documentFromLocalFile(
     parentId: parentFolderId(file.path),
     title: parsed.title,
     content: parsed.content,
+    description: parsed.description ?? "",
     icon: parsed.icon ?? null,
     position,
     isFavorite: parsed.isFavorite ?? false,
@@ -410,6 +412,33 @@ export async function getLocalFileDocument(id: string): Promise<Document> {
   return documentFromLocalFile(file, file.content, 0);
 }
 
+export async function getLocalDocumentContextPath(id: string) {
+  const documents = await listLocalFileDocuments();
+  const byId = new Map(documents.map((document) => [document.id, document]));
+  const current = byId.get(id) ?? (await getLocalFileDocument(id));
+  const path: Array<{
+    id: string;
+    kind: "page" | "database";
+    title: string;
+    description: string;
+  }> = [];
+  const seen = new Set([current.id]);
+  let parentId = current.parentId;
+  while (parentId && !seen.has(parentId)) {
+    seen.add(parentId);
+    const parent = byId.get(parentId);
+    if (!parent) break;
+    path.unshift({
+      id: parent.id,
+      kind: "page",
+      title: parent.title,
+      description: parent.description ?? "",
+    });
+    parentId = parent.parentId;
+  }
+  return path;
+}
+
 function splitFrontmatter(source: string) {
   const match = source.match(FRONTMATTER_RE);
   if (!match) return { frontmatter: "", body: source };
@@ -517,12 +546,16 @@ function updateFrontmatterFields(
   titleChanged: boolean,
   iconChanged: boolean,
   favoriteChanged: boolean,
+  descriptionChanged: boolean,
 ) {
   if (usesDocsNoBookkeepingProfile(file.profile)) {
     return {
       ...(titleChanged ? { title: nextTitle || "Untitled" } : {}),
       ...(iconChanged ? { icon: args.icon ?? null } : {}),
       ...(favoriteChanged ? { isFavorite: args.isFavorite ?? false } : {}),
+      ...(descriptionChanged
+        ? { description: args.description?.trim() ?? "" }
+        : {}),
     };
   }
 
@@ -531,6 +564,10 @@ function updateFrontmatterFields(
     icon: args.icon !== undefined ? args.icon : current.icon,
     isFavorite:
       args.isFavorite !== undefined ? args.isFavorite : current.isFavorite,
+    description:
+      args.description !== undefined
+        ? args.description.trim()
+        : current.description,
     updatedAt: new Date().toISOString(),
   };
 }
@@ -544,6 +581,9 @@ function createFrontmatterFields(
     return {
       title,
       ...(args.icon !== undefined ? { icon: args.icon || null } : {}),
+      ...(args.description !== undefined
+        ? { description: args.description.trim() }
+        : {}),
     };
   }
 
@@ -551,6 +591,7 @@ function createFrontmatterFields(
     title,
     icon: args.icon || null,
     isFavorite: false,
+    description: args.description?.trim() ?? "",
     updatedAt: new Date().toISOString(),
   };
 }
@@ -576,8 +617,17 @@ export async function updateLocalFileDocument(
   const iconChanged = args.icon !== undefined && args.icon !== current.icon;
   const favoriteChanged =
     args.isFavorite !== undefined && args.isFavorite !== current.isFavorite;
+  const descriptionChanged =
+    args.description !== undefined &&
+    args.description.trim() !== current.description;
 
-  if (!titleChanged && !contentChanged && !iconChanged && !favoriteChanged) {
+  if (
+    !titleChanged &&
+    !contentChanged &&
+    !iconChanged &&
+    !favoriteChanged &&
+    !descriptionChanged
+  ) {
     return current;
   }
 
@@ -591,6 +641,7 @@ export async function updateLocalFileDocument(
       titleChanged,
       iconChanged,
       favoriteChanged,
+      descriptionChanged,
     ),
     nextContent,
   );
@@ -712,6 +763,7 @@ export async function localContentViewScreenSummary() {
       id: document.id,
       parentId: document.parentId,
       title: document.title,
+      description: document.description,
       source: document.source,
     })),
   };

package/corpus/templates/content/actions/_property-utils.ts

@@ -151,11 +151,15 @@ export async function getDatabaseById(
   return database ?? null;
 }
 
-export function serializeDatabase(database: ContentDatabaseRow) {
+export function serializeDatabase(
+  database: ContentDatabaseRow,
+  description = "",
+) {
   return {
     id: database.id,
     documentId: database.documentId,
     title: database.title,
+    description,
     viewConfig: parseDatabaseViewConfig(database.viewConfigJson),
     createdAt: database.createdAt,
     updatedAt: database.updatedAt,
@@ -500,6 +504,7 @@ export async function listPropertiesForDatabase(
         databaseId: definition.databaseId,
         name: definition.name,
         type,
+        description: definition.description,
         visibility: normalizePropertyVisibility(definition.visibility),
         options,
         position: definition.position,
@@ -568,6 +573,7 @@ function serializePropertyDefinition(
     databaseId: definition.databaseId,
     name: definition.name,
     type,
+    description: definition.description,
     visibility: normalizePropertyVisibility(definition.visibility),
     options: parsePropertyOptions(definition.optionsJson),
     position: definition.position,

package/corpus/templates/content/actions/configure-document-property.ts

@@ -36,6 +36,12 @@ export default defineAction({
       .string()
       .describe("Document ID used to scope the property workspace"),
     name: z.string().min(1).describe("Property name"),
+    description: z
+      .string()
+      .optional()
+      .describe(
+        "Stable guidance describing what this property means and which value belongs here",
+      ),
     type: z.enum(CREATABLE_DOCUMENT_PROPERTY_TYPES).describe("Property type"),
     visibility: z
       .enum(DOCUMENT_PROPERTY_VISIBILITIES)
@@ -49,6 +55,7 @@ export default defineAction({
               id: z.string(),
               name: z.string(),
               color: z.string(),
+              description: z.string().optional(),
             }),
           )
           .optional(),
@@ -162,6 +169,9 @@ export default defineAction({
         .update(schema.documentPropertyDefinitions)
         .set({
           name,
+          ...(args.description === undefined
+            ? {}
+            : { description: args.description.trim() }),
           type,
           visibility:
             args.visibility === undefined
@@ -196,6 +206,7 @@ export default defineAction({
             orgId: document.orgId ?? null,
             databaseId: database.id,
             name,
+            description: args.description?.trim() ?? "",
             type,
             visibility: normalizePropertyVisibility(args.visibility),
             optionsJson,

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({