@agent-native/core 0.101.6 → 0.101.10

package/corpus/templates/calendar/app/components/calendar/WeekView.tsx

@@ -43,6 +43,11 @@ import {
   partitionAllDayEvents,
 } from "@/lib/all-day-layout";
 import { getEventDisplayColor, allOtherDeclined } from "@/lib/event-colors";
+import {
+  getFirstVisibleOutOfOfficeDayIndex,
+  getOutOfOfficeSegment,
+  isOutOfOfficeEvent,
+} from "@/lib/out-of-office";
 import {
   shouldSuppressAfterPopoverClose,
   shouldSuppressCreatePointerDown,
@@ -56,6 +61,7 @@ import {
 } from "@/lib/working-location";
 
 import { EventDetailPopover } from "./EventDetailPopover";
+import { OutOfOfficeEvent } from "./OutOfOfficeEvent";
 import { shouldRenderWeekDragSegment } from "./week-drag-segment";
 
 interface WeekViewProps {
@@ -285,6 +291,7 @@ interface WeekEventCardProps {
   onDraftUpdate?: WeekViewProps["onDraftUpdate"];
   onDraftCreate?: WeekViewProps["onDraftCreate"];
   onDraftDiscard?: WeekViewProps["onDraftDiscard"];
+  onPopoverOpenChange: (event: CalendarEvent, open: boolean) => void;
 }
 
 /**
@@ -320,6 +327,7 @@ const WeekEventCard = memo(function WeekEventCard({
   onDraftUpdate,
   onDraftCreate,
   onDraftDiscard,
+  onPopoverOpenChange,
 }: WeekEventCardProps) {
   const t = useT();
   const li = layout.get(event.id) ?? {
@@ -558,6 +566,7 @@ const WeekEventCard = memo(function WeekEventCard({
       onDraftUpdate={onDraftUpdate}
       onDraftCreate={onDraftCreate}
       onDraftDiscard={onDraftDiscard}
+      onOpenChange={(open) => onPopoverOpenChange(event, open)}
     >
       {eventButton}
     </EventDetailPopover>
@@ -618,6 +627,7 @@ export const WeekView = memo(function WeekView({
   const GUTTER_WIDTH = isMobile ? MOBILE_GUTTER_WIDTH : DESKTOP_GUTTER_WIDTH;
   const [now, setNow] = useState(new Date());
   const [focusedEventId, setFocusedEventId] = useState<string | null>(null);
+  const focusedEventIdRef = useRef<string | null>(null);
   const currentTimeRef = useRef<HTMLDivElement>(null);
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const allDayContainerRef = useRef<HTMLDivElement>(null);
@@ -628,6 +638,7 @@ export const WeekView = memo(function WeekView({
   useEffect(() => {
     function handleKey(e: KeyboardEvent) {
       if (e.key === "Escape") {
+        focusedEventIdRef.current = null;
         setFocusedEventId(null);
         setFocusedEvent(null);
       }
@@ -675,7 +686,15 @@ export const WeekView = memo(function WeekView({
   // Separate all-day and timed events
   const allDayEvents = useMemo(() => events.filter((e) => e.allDay), [events]);
 
-  const timedEvents = useMemo(() => events.filter((e) => !e.allDay), [events]);
+  const outOfOfficeEvents = useMemo(
+    () => events.filter((event) => !event.allDay && isOutOfOfficeEvent(event)),
+    [events],
+  );
+
+  const timedEvents = useMemo(
+    () => events.filter((event) => !event.allDay && !isOutOfOfficeEvent(event)),
+    [events],
+  );
 
   const { workingLocations, regularEvents } = useMemo(
     () => partitionAllDayEvents(allDayEvents),
@@ -849,6 +868,22 @@ export const WeekView = memo(function WeekView({
 
   const canDrag = !!onEventTimeChange;
 
+  const handleEventPopoverOpenChange = useCallback(
+    (event: CalendarEvent, open: boolean) => {
+      if (open) {
+        focusedEventIdRef.current = event.id;
+        setFocusedEventId(event.id);
+        setFocusedEvent(event);
+        return;
+      }
+      if (focusedEventIdRef.current !== event.id) return;
+      focusedEventIdRef.current = null;
+      setFocusedEventId(null);
+      setFocusedEvent(null);
+    },
+    [setFocusedEvent],
+  );
+
   const handleEventPointerDown = useCallback(
     (
       e: React.PointerEvent,
@@ -856,6 +891,7 @@ export const WeekView = memo(function WeekView({
       isStart: boolean,
       dayIndex: number,
     ) => {
+      focusedEventIdRef.current = event.id;
       setFocusedEventId(event.id);
       setFocusedEvent(event);
       if (
@@ -1262,6 +1298,16 @@ export const WeekView = memo(function WeekView({
               }
             }
 
+            const visibleOutOfOfficeEvents = outOfOfficeEvents.filter(
+              (event) => {
+                const overrides = getDragOverrides(event.id);
+                return (
+                  getOutOfOfficeSegment(event, day) !== null ||
+                  (dragEventId === event.id && overrides?.dayIndex === dayIndex)
+                );
+              },
+            );
+
             return (
               <div
                 key={day.toISOString()}
@@ -1338,6 +1384,73 @@ export const WeekView = memo(function WeekView({
                   </div>
                 )}
 
+                {/* Native Google out-of-office context sits behind meetings. */}
+                {!isLoading &&
+                  visibleOutOfOfficeEvents.map((event, markerIndex) => {
+                    const isBeingDragged = dragEventId === event.id;
+                    const overrides = getDragOverrides(event.id);
+                    const canonicalDayIndex =
+                      getFirstVisibleOutOfOfficeDayIndex(event, days);
+                    return (
+                      <OutOfOfficeEvent
+                        key={`${event._tempId ?? event.id}:${day.toISOString()}`}
+                        event={event}
+                        day={day}
+                        hourHeight={HOUR_HEIGHT}
+                        color={
+                          getEventDisplayColor(event, prefs) ??
+                          "hsl(var(--primary))"
+                        }
+                        label={t("eventForm.outOfOffice")}
+                        markerIndex={markerIndex}
+                        compactMarker
+                        canDrag={canDrag}
+                        isBeingDragged={isBeingDragged}
+                        isDragging={isDragging}
+                        isDragTargetDay={overrides?.dayIndex === dayIndex}
+                        overrideTop={overrides?.top ?? null}
+                        overrideHeight={overrides?.height ?? null}
+                        onMovePointerDown={(pointerEvent, startsOnDay) =>
+                          handleEventPointerDown(
+                            pointerEvent,
+                            event,
+                            startsOnDay,
+                            dayIndex,
+                          )
+                        }
+                        onResizeTopPointerDown={(pointerEvent) =>
+                          handleResizeTopPointerDown(
+                            pointerEvent,
+                            event.id,
+                            dayIndex,
+                          )
+                        }
+                        onResizeBottomPointerDown={(pointerEvent) =>
+                          handleResizeBottomPointerDown(
+                            pointerEvent,
+                            event.id,
+                            dayIndex,
+                          )
+                        }
+                        shouldSuppressClick={shouldSuppressClick}
+                        onDelete={onDeleteEvent}
+                        isDraft={draftEventIds.includes(event.id)}
+                        defaultOpen={
+                          quickEditEventId === event.id &&
+                          dayIndex === canonicalDayIndex
+                        }
+                        onTitleSave={onQuickEditSave}
+                        onDismissNew={onQuickEditCancel}
+                        onDraftUpdate={onDraftUpdate}
+                        onDraftCreate={onDraftCreate}
+                        onDraftDiscard={onDraftDiscard}
+                        onOpenChange={(open) =>
+                          handleEventPopoverOpenChange(event, open)
+                        }
+                      />
+                    );
+                  })}
+
                 {/* Skeleton events when loading */}
                 {isLoading &&
                   WEEK_SKELETONS[dayIndex]?.map(
@@ -1402,6 +1515,7 @@ export const WeekView = memo(function WeekView({
                         onDraftUpdate={onDraftUpdate}
                         onDraftCreate={onDraftCreate}
                         onDraftDiscard={onDraftDiscard}
+                        onPopoverOpenChange={handleEventPopoverOpenChange}
                       />
                     );
                   })}

package/corpus/templates/calendar/app/lib/out-of-office.ts

@@ -0,0 +1,45 @@
+import type { CalendarEvent } from "@shared/api";
+import { addDays, differenceInMinutes, parseISO, startOfDay } from "date-fns";
+
+export interface OutOfOfficeSegment {
+  topMinutes: number;
+  durationMinutes: number;
+  startsOnDay: boolean;
+  endsOnDay: boolean;
+}
+
+export function isOutOfOfficeEvent(
+  event: Pick<CalendarEvent, "eventType">,
+): boolean {
+  return event.eventType === "outOfOffice";
+}
+
+/** Return the portion of a timed out-of-office event visible on one day. */
+export function getOutOfOfficeSegment(
+  event: Pick<CalendarEvent, "start" | "end">,
+  day: Date,
+): OutOfOfficeSegment | null {
+  const eventStart = parseISO(event.start);
+  const eventEnd = parseISO(event.end);
+  const dayStart = startOfDay(day);
+  const dayEnd = addDays(dayStart, 1);
+
+  if (eventStart >= dayEnd || eventEnd <= dayStart) return null;
+
+  const segmentStart = eventStart > dayStart ? eventStart : dayStart;
+  const segmentEnd = eventEnd < dayEnd ? eventEnd : dayEnd;
+
+  return {
+    topMinutes: Math.max(0, differenceInMinutes(segmentStart, dayStart)),
+    durationMinutes: Math.max(1, differenceInMinutes(segmentEnd, segmentStart)),
+    startsOnDay: eventStart >= dayStart && eventStart < dayEnd,
+    endsOnDay: eventEnd > dayStart && eventEnd <= dayEnd,
+  };
+}
+
+export function getFirstVisibleOutOfOfficeDayIndex(
+  event: Pick<CalendarEvent, "start" | "end">,
+  days: Date[],
+): number {
+  return days.findIndex((day) => getOutOfOfficeSegment(event, day) !== null);
+}

package/corpus/templates/calendar/changelog/2026-07-14-out-of-office-blocks-now-sit-behind-meetings-and-event-stack.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-14
+---
+
+Out-of-office blocks now sit behind meetings, and event stacking resets after closing details.

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                                                                               |
@@ -123,13 +123,14 @@ cd templates/content && pnpm action <name> [args]
 | `change-content-database-source-role`       | `--databaseId <id>` or `--documentId <id> --sourceId <id> --relationshipMode items\|details [--join <json>]`                                                                                       | Change an attached source between adding rows and adding matched detail columns without removing the source                                                                       |
 | `refresh-content-database-source`           | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Refresh the read-only source status envelope; large Builder CMS sources may return a partial fetch, and another refresh continues loading remaining rows                          |
 | `process-builder-body-hydration`            | `--sourceId <id> [--documentId <id>] [--limit <n>]`                                                                                                                                                | Hydrate queued Builder article bodies into readable Content markdown with preserved source-component markers                                                                      |
-| `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> --liveWritesEnabled true\|false [--allowedWriteModes <json>]`                                                                                            | Enable/disable per-source Builder live writes; enabling is allowed only for `agent-native-blog-article-test` with explicit modes                                                  |
+| `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> [--sourceId <id>] --writeMode read_only\|stage_only\|publish_updates [--allowPublicationTransitions true\|false]`                                        | Set the per-source Builder write tier; requires page admin access and remains read-only by default                                                                                |
 | `stage-builder-revision`                    | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Stage pending local Builder CMS changes as a local-only save-revision record; never calls Builder                                                                                 |
 | `review-content-database-source-change-set` | `--databaseId <id>` or `--documentId <id> --changeSetId <id> --decision approve\|reject [--note]`                                                                                                  | Approve or reject a local source change-set review record without provider writes                                                                                                 |
 | `stage-builder-source-bulk-update`          | `--databaseId <id>` or `--documentId <id> --itemIds <json-array>` or `--documentIds <json-array> --field <json> [--sourceId <id>] [--dryRun true\|false]`                                          | Preview or stage one bounded field update across selected source-backed Builder rows; apply still goes through Builder review/execution                                           |
 | `prepare-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--pushModeConfirmation autosave\|draft\|publish]`                                                                                    | Prepare a dry-run Builder execution gate for approved field/body changes with request semantics/idempotency key; never calls Builder                                              |
 | `validate-builder-source-execution`         | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>]`                                                                                                             | Validate/replay a prepared Builder execution gate locally as a dry run; never calls Builder                                                                                       |
-| `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                                                           | Execute a guarded live Builder write only when approved, validated, enabled, idempotent, and targeting `agent-native-blog-article-test`                                           |
+| `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                                                           | Execute a guarded live Builder write only when approved, validated, enabled for that source, and idempotent                                                                       |
+| `cancel-prepared-builder-source-update`     | `--databaseId <id>` or `--documentId <id> --sourceId <id> --changeSetId <id> [--note <text>]`                                                                                                      | Cancel an exact prepared Builder update only when every associated execution is provably pre-dispatch; preserves review and execution history and never calls Builder             |
 | `add-database-item`                         | `--databaseId <id> [--title <text>] [--propertyValues <json>]`                                                                                                                                     | Add a page row to a database, optionally seeding property values                                                                                                                  |
 | `submit-content-database-form`              | `--databaseId <id> [--viewId <form-view-id>] [--title <text>] [--propertyValues <json>]`                                                                                                           | Submit one form response atomically; validates required questions, resolves option labels/IDs, writes Blocks correctly, verifies persistence, and returns the exact row page link |
 | `duplicate-database-item`                   | `--itemId <id>` or `--documentId <id> [--title <text>]`                                                                                                                                            | Duplicate exactly one database row page and its stored property values; for two or more rows, use `duplicate-database-items` once                                                 |
@@ -138,7 +139,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 +152,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 +410,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/_builder-cms-intent-lookup.ts

@@ -0,0 +1,87 @@
+import { isDeepStrictEqual } from "node:util";
+
+import { BUILDER_CMS_SAFE_WRITE_MODEL } from "../shared/api.js";
+import { readBuilderCmsContentEntries } from "./_builder-cms-read-client.js";
+import type { BuilderCmsSourceEntry } from "./_builder-cms-source-adapter.js";
+import { BUILDER_CMS_EXECUTION_MARKER_FIELD } from "./_builder-cms-write-adapter.js";
+
+export interface BuilderCmsIntentMatch {
+  id: string;
+  title: string;
+  lastUpdated: string | null;
+  published: string | null;
+}
+
+export function matchBuilderCmsSafeModelIntentEntries(
+  entries: BuilderCmsSourceEntry[],
+  args: {
+    marker?: string;
+    exactTitle?: string;
+    intendedFields?: Record<string, unknown>;
+  },
+) {
+  const identityMatches = entries.filter((entry) => {
+    const data = rawRecord(entry.rawEntry?.data);
+    if (args.marker) {
+      return data?.[BUILDER_CMS_EXECUTION_MARKER_FIELD] === args.marker;
+    }
+    const title = data?.title;
+    return (
+      typeof title === "string" && title.trim() === args.exactTitle?.trim()
+    );
+  });
+  const matchingIntent = identityMatches.filter((entry) => {
+    const data = rawRecord(entry.rawEntry?.data);
+    return Object.entries(args.intendedFields ?? {}).every(([key, value]) =>
+      isDeepStrictEqual(data?.[key], value),
+    );
+  });
+  return {
+    count: identityMatches.length,
+    matchingIntentCount: matchingIntent.length,
+    matches: identityMatches.map(compactMatch),
+  };
+}
+
+function rawRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function compactMatch(entry: BuilderCmsSourceEntry): BuilderCmsIntentMatch {
+  const raw = rawRecord(entry.rawEntry);
+  return {
+    id: entry.id,
+    title: entry.title,
+    lastUpdated:
+      typeof raw?.lastUpdated === "string" ||
+      typeof raw?.lastUpdated === "number"
+        ? String(raw.lastUpdated)
+        : entry.updatedAt || null,
+    published: typeof raw?.published === "string" ? raw.published : null,
+  };
+}
+
+export async function lookupBuilderCmsSafeModelIntent(args: {
+  marker?: string;
+  exactTitle?: string;
+  intendedFields?: Record<string, unknown>;
+}) {
+  if (!args.marker && !args.exactTitle) {
+    throw new Error("Provide an exact execution marker or exact title.");
+  }
+  const result = await readBuilderCmsContentEntries({
+    model: BUILDER_CMS_SAFE_WRITE_MODEL,
+    rawData: true,
+    requirePrivateKey: true,
+    limit: 10_000,
+  });
+  if (result.state !== "live" || result.progress.partial) {
+    throw new Error(
+      result.message ??
+        "Builder safe-model lookup was incomplete; reconciliation cannot proceed.",
+    );
+  }
+  return matchBuilderCmsSafeModelIntentEntries(result.entries, args);
+}