@agent-native/core 0.101.5 → 0.101.7

package/corpus/templates/clips/desktop/src-tauri/src/whisper_speech.rs

@@ -495,14 +495,22 @@ mod macos {
         let mut out = Vec::new();
         for segment in state.as_iter() {
             let text = segment.to_string();
-            if is_speech(&text) && segment.no_speech_probability() < MAX_NO_SPEECH_PROBABILITY {
-                // whisper timestamps are in centiseconds → ms.
-                out.push((
-                    segment.start_timestamp() * 10,
-                    segment.end_timestamp() * 10,
-                    text,
-                ));
+            if !is_speech(&text) || segment.no_speech_probability() >= MAX_NO_SPEECH_PROBABILITY {
+                continue;
+            }
+            // Low average token confidence means whisper was guessing —
+            // typically a mis-detected-language hallucination that reads
+            // fluently but scores poorly. Drop it.
+            let confidence = segment_confidence(&segment);
+            if confidence < MIN_AVG_TOKEN_PROBABILITY {
+                continue;
             }
+            // whisper timestamps are in centiseconds → ms.
+            out.push((
+                segment.start_timestamp() * 10,
+                segment.end_timestamp() * 10,
+                text,
+            ));
         }
         out
     }
@@ -530,6 +538,40 @@ mod macos {
     const VOICE_RMS_THRESHOLD: f32 = 0.006;
     /// A second, model-level gate for ambient/no-speech Whisper segments.
     const MAX_NO_SPEECH_PROBABILITY: f32 = 0.72;
+    /// Minimum average per-token probability for a segment to count as real
+    /// speech. On noisy/near-silent audio whisper mis-detects the language and
+    /// decodes fluent-looking gibberish in another language — but those tokens
+    /// are low-confidence under the hood. Dropping segments below this cutoff
+    /// removes that wrong-language garbage while keeping genuine multilingual
+    /// speech (which decodes with high confidence).
+    const MIN_AVG_TOKEN_PROBABILITY: f32 = 0.55;
+
+    /// Average the model's per-token probability across a segment. Returns 0.0
+    /// for an empty segment so it is treated as low-confidence. Special tokens
+    /// (timestamps, `[_BEG_]`, …) render as `[_…]` and are skipped so they
+    /// don't skew the average toward the text tokens we actually care about.
+    fn segment_confidence(segment: &whisper_rs::WhisperSegment<'_>) -> f32 {
+        let mut sum = 0.0f32;
+        let mut count = 0u32;
+        for i in 0..segment.n_tokens() {
+            let Some(token) = segment.get_token(i) else {
+                continue;
+            };
+            let is_special = token
+                .to_str_lossy()
+                .map(|t| t.starts_with("[_"))
+                .unwrap_or(false);
+            if is_special {
+                continue;
+            }
+            sum += token.token_probability();
+            count += 1;
+        }
+        if count == 0 {
+            return 0.0;
+        }
+        sum / count as f32
+    }
 
     fn partial_inference_due(
         emit_partials: bool,

package/corpus/templates/clips/server/lib/recordings.ts

@@ -6,7 +6,7 @@ import {
   getRequestOrgId,
 } from "@agent-native/core/server/request-context";
 import { and, desc, eq, sql } from "drizzle-orm";
-import type { H3Event } from "h3";
+import { HTTPError, type H3Event } from "h3";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -120,7 +120,10 @@ export async function requireOrganizationAccess(
   const email = getCurrentOwnerEmail();
   const role = await getOrganizationRoleForEmail(resolvedOrganizationId, email);
   if (!role || !organizationRoleAllowed(role, allowedRoles)) {
-    throw new Error("Organization not found or access denied");
+    throw new HTTPError({
+      statusCode: 403,
+      statusMessage: "Organization not found or access denied",
+    });
   }
   return { organizationId: resolvedOrganizationId, email, role };
 }

package/corpus/templates/content/.agents/skills/content/SKILL.md

@@ -101,6 +101,37 @@ inferences for confirmation, then submit once. When required information is
 missing, keep the clarification in the originating thread and retain earlier
 answers as context.
 
+### Slack Follow-ups And Corrections
+
+A follow-up in an existing Slack thread is not automatically a new intake. Read
+the thread context and inspect the prior Content artifact identity first,
+including any returned document ID or `/page/<id>` path and the canonical
+database row when available. Then choose the operation that matches the user's
+intent:
+
+- **Update** the same document for corrections, refinements, status changes, or
+  renames that still describe the same request. A rename changes the title, not
+  the artifact identity: preserve the stable Content document ID and page path.
+- **Add** new details to the same document when the follow-up extends the
+  original request without replacing it.
+- **Supersede** only when the user intends a replacement artifact or distinct
+  successor and the workspace's schema or instructions define how that
+  relationship is recorded. Preserve a concrete link to the prior artifact.
+- **Create** only when the follow-up is genuinely a separate request or the user
+  explicitly asks for a new artifact. Do not blindly submit another row merely
+  because a new Slack message arrived.
+
+Apply people fields from verified identity and intent, not from convenient
+guesswork:
+
+- When the database has a `Requester` field, default it to the verified Slack
+  sender unless the user explicitly identifies a different requester.
+- A named doer such as "for Apoorva" maps to `Assignee` when that field exists.
+  Naming an assignee never changes or replaces `Requester`.
+- Resolve named people to the database's accepted person identity before
+  writing. If a named person cannot be resolved unambiguously, clarify in the
+  originating Slack thread; never omit, downgrade, or silently drop the person.
+
 ## Local File Mode
 
 Install into an existing repo with:

package/corpus/templates/content/.agents/skills/document-editing/SKILL.md

@@ -7,7 +7,10 @@ description: >-
 
 # Document Editing
 
-Documents are stored in the SQL database via Drizzle ORM. Each document has a title, markdown content, optional parent (for nesting), and a position for ordering.
+Documents are stored in the SQL database via Drizzle ORM. Each document has a
+title, stable description, markdown content, optional parent (for nesting), and
+a position for ordering. The description explains why the page exists and what
+belongs there; it is not a changing synopsis of the current body.
 
 ## Scripts
 
@@ -48,6 +51,7 @@ Create a new document.
 pnpm action create-document --title "Meeting Notes" --content "# Meeting Notes\n\nAttendees: ..."
 pnpm action create-document --title "Sub Page" --parentId parent123
 pnpm action create-document --title "My Page" --icon "📝"
+pnpm action create-document --title "Research" --description "Evidence and source notes that support the current project"
 ```
 
 ### edit-document
@@ -73,6 +77,7 @@ Update an existing document. Use for **full rewrites or new content**, not for s
 pnpm action update-document --id abc123 --title "New Title"
 pnpm action update-document --id abc123 --content "# Updated Content\n\nNew text here"
 pnpm action update-document --id abc123 --title "New Title" --content "New content"
+pnpm action update-document --id abc123 --description "Stable guidance for what belongs on this page"
 ```
 
 ### delete-document
@@ -123,17 +128,18 @@ Always run this after any document modification to update the sidebar.
 
 ## Document Schema
 
-| Column       | Type    | Description                             |
-| ------------ | ------- | --------------------------------------- |
-| `id`         | text    | Primary key (12-char hex string)        |
-| `parent_id`  | text    | Parent document ID (null for root)      |
-| `title`      | text    | Document title (default: "Untitled")    |
-| `content`    | text    | Markdown content                        |
-| `icon`       | text    | Emoji icon (optional)                   |
-| `position`   | integer | Sort order within parent (0-based)      |
-| `is_favorite`| integer | Whether document is favorited (0 or 1)  |
-| `created_at` | text    | ISO timestamp                           |
-| `updated_at` | text    | ISO timestamp                           |
+| Column        | Type    | Description                            |
+| ------------- | ------- | -------------------------------------- |
+| `id`          | text    | Primary key (12-char hex string)       |
+| `parent_id`   | text    | Parent document ID (null for root)     |
+| `title`       | text    | Document title (default: "Untitled")   |
+| `description` | text    | Stable semantic guidance for the page  |
+| `content`     | text    | Markdown content                       |
+| `icon`        | text    | Emoji icon (optional)                  |
+| `position`    | integer | Sort order within parent (0-based)     |
+| `is_favorite` | integer | Whether document is favorited (0 or 1) |
+| `created_at`  | text    | ISO timestamp                          |
+| `updated_at`  | text    | ISO timestamp                          |
 
 ## Content Format
 
@@ -142,21 +148,29 @@ Documents use **markdown** for content. The editor renders markdown in real time
 ## Parent-Child Hierarchy
 
 Documents form a tree via `parent_id`:
+
 - Root documents have `parent_id = null`
 - Child documents reference their parent's `id`
 - Deleting a parent recursively deletes all children
 - Position determines ordering within the same parent
 
+Descriptions are owned; context is inherited. `get-document` and `view-screen`
+return the focused page's own description plus a computed root-to-parent
+`contextPath`. Use that path to understand where the page lives, but never copy
+ancestor descriptions into the child. Database, property, and option
+descriptions narrow the guidance further when working with structured values.
+
 ## Common Tasks
 
-| User says                     | What to do                                                       |
-| ----------------------------- | ---------------------------------------------------------------- |
-| "Create a page about X"       | `create-document --title "X" --content "# X\n\n..."`           |
-| "Find my meeting notes"       | `search-documents --query "meeting notes"`                      |
-| "Fix a typo / edit a line"    | `view-screen` to get ID, then `edit-document --id ... --find "old" --replace "new"` |
-| "Rewrite this document"       | `view-screen` to get ID, then `update-document --id ... --content ...` |
-| "Delete this page"            | `view-screen` to get ID, then `delete-document --id ...`       |
-| "Add a sub-page"              | `create-document --title "Sub" --parentId <parentId>`           |
-| "Show me the document tree"   | `list-documents`                                                |
+| User says                    | What to do                                                                          |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| "Create a page about X"      | `create-document --title "X" --content "# X\n\n..."`                                |
+| "Describe what belongs here" | `update-document --id ... --description "..."`                                      |
+| "Find my meeting notes"      | `search-documents --query "meeting notes"`                                          |
+| "Fix a typo / edit a line"   | `view-screen` to get ID, then `edit-document --id ... --find "old" --replace "new"` |
+| "Rewrite this document"      | `view-screen` to get ID, then `update-document --id ... --content ...`              |
+| "Delete this page"           | `view-screen` to get ID, then `delete-document --id ...`                            |
+| "Add a sub-page"             | `create-document --title "Sub" --parentId <parentId>`                               |
+| "Show me the document tree"  | `list-documents`                                                                    |
 
 Always run `refresh-list` after any create, update, or delete operation.

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,