@crossworks/client-types 0.232.356 → 0.232.365

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/client-types",
-  "version": "0.232.356",
+  "version": "0.232.365",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/app-nav.ts

@@ -29,6 +29,7 @@ export const APP_TINTS = [
   'lime',
   'green',
   'teal',
+  'cyan',
   'sky',
   'blue',
   'indigo',

package/src/dto/access.ts

@@ -26,7 +26,8 @@ export type AccessLinkView = {
   token: string;
   path: string;
   mode: ShareMode;
-  /** Page links only: sub-pages are shared with it. */
+  /** DEPRECATED (folder phase 7): a page link no longer shares sub-pages
+   *  (pages do not nest); always false. Kept for older clients. */
   cascade: boolean;
 };
 
@@ -52,7 +53,8 @@ export type AccessNodeView = {
    *  contents, which keep their own levels. */
   closure: AccessItemView[];
   share: AccessLinkView | null;
-  /** Descendant pages (pages only; 0 otherwise). */
+  /** DEPRECATED (folder phase 7): pages do not nest, so always 0. Kept for
+   *  older clients, which showed "Include sub-pages" above 0. */
   childCount: number;
   /** Only workspace kinds go below admin (tasks, events, … are admin only). */
   canLower: boolean;
@@ -77,6 +79,30 @@ export type AccessNodeView = {
   /** The shared folder it takes its share from (folder sharing); null when
    *  none. Absent from brains before folder sharing. */
   sharedVia?: AccessSharedVia | null;
+  /** What it is read through by embeds (migration 0208); null when nothing
+   *  reaches it. Absent from brains before 0208. */
+  readThrough?: AccessReadThrough | null;
+};
+
+/** An item is read through the items that embed it (migration 0208): a
+ *  shared note makes its image readable wherever the image lives. The item
+ *  is read at least at `level`, whatever its own level says, so the control
+ *  offers nothing above it: take the embed out, or move the embedder out of
+ *  its shared folder, to hide it. */
+export type AccessReadThrough = {
+  level: 'team' | 'client';
+  /** The nearest items that embed it and carry a share, most open first
+   *  (at most five). */
+  via: Array<{
+    id: string;
+    title: string;
+    /** The node type ('note', 'page', 'draw', ...). */
+    type: string;
+    level: 'team' | 'client';
+    /** 'folder': shared by its own folder; 'embed': itself read through
+     *  another embed. */
+    through: 'folder' | 'embed';
+  }>;
 };
 
 /** The nearest shared folder holding an item (folder sharing, phase 4). The

package/src/dto/client.ts

@@ -61,7 +61,7 @@ export type ClientSharedPage = {
  *  a mention chip or a link names "Private item" and points nowhere, an
  *  embed of such an item is left out. */
 export type ClientSharedItem =
-  | (ClientSharedRow & { type: 'page'; doc: unknown })
+  | (ClientSharedRow & { type: 'page'; doc: unknown; folderId?: string | null })
   | (ClientSharedRow & { type: 'note'; content: string })
   | (ClientSharedRow & { type: 'table'; table: ClientSharedTable })
   | (ClientSharedRow & { type: 'draw' })
@@ -342,7 +342,7 @@ export type ClientSpaceRefusedReason =
  *  current version). A file's bytes: /api/client/files/:id while the brain
  *  file still holds the bytes accepted (`changedByAdmin` otherwise). */
 export type ClientAcceptedItem =
-  | (ClientAcceptedBase & { type: 'page'; doc: unknown })
+  | (ClientAcceptedBase & { type: 'page'; doc: unknown; folderId?: string | null })
   | (ClientAcceptedBase & { type: 'note'; content: string })
   | (ClientAcceptedBase & {
       type: 'file';

package/src/dto/member.ts

@@ -64,7 +64,7 @@ export type MemberLibraryPage = {
 
 /** GET /api/member/library/:id -> { item } */
 export type MemberLibraryItem =
-  | (MemberLibraryRow & { type: 'page'; doc: unknown })
+  | (MemberLibraryRow & { type: 'page'; doc: unknown; folderId?: string | null })
   | (MemberLibraryRow & { type: 'note'; content: string })
   | (MemberLibraryRow & { type: 'table'; table: unknown })
   | (MemberLibraryRow & { type: 'draw' })
@@ -248,7 +248,7 @@ export type MemberAcceptedPage = {
  *  saved picture) since, so its bytes are not served any more; the metadata
  *  is what was accepted. */
 export type MemberAcceptedItem =
-  | (MemberAcceptedRow & { type: 'page'; doc: unknown })
+  | (MemberAcceptedRow & { type: 'page'; doc: unknown; folderId?: string | null })
   | (MemberAcceptedRow & { type: 'note'; content: string })
   | (MemberAcceptedRow & { type: 'table'; table: unknown })
   | (MemberAcceptedRow & { type: 'draw'; changedByAdmin?: boolean })

package/src/dto/recall.ts

@@ -14,8 +14,6 @@ export type {
   RecallActorKind,
   RecallCardDetailDTO,
   RecallCardWriteDTO,
-  RecallLintIssueDTO,
-  RecallLintSeverity,
   RecallMapCreateDTO,
   RecallMapCreateResultDTO,
   RecallMapDetailDTO,
@@ -23,7 +21,6 @@ export type {
   RecallMapSummaryDTO,
   RecallNodeDTO,
   RecallOptionDTO,
-  RecallPageStateDTO,
   RecallRevisionDTO,
   RecallWarningDTO,
   RecallWriteErrorDTO,

package/src/dto/review.ts

@@ -5,7 +5,7 @@
  * the wire, so an older brain or an older client keeps working.
  */
 import type { AccessItemView, AccessLevel } from './access';
-import type { TreeCrumb, TreeKind } from '../tree';
+import type { TreeCrumb, TreeKind, TreeShareLevel, TreeVisibilityChange } from '../tree';
 
 /** Who wrote a reviewable item: a member or a client login. */
 export type ReviewAuthorRole = 'member' | 'client';
@@ -32,8 +32,8 @@ export type AcceptPreview = {
   closure?: AccessItemView[];
   /** Where it lands by default (folder plan phase 5): the brain folder the
    *  author filed it in (`folderId` null = the kind's top level), and the
-   *  author's own folders that become brain folders below it. Absent for a
-   *  page (no tree yet) and from brains before the tree. */
+   *  author's own folders that become brain folders below it. Absent from
+   *  brains before the tree (pages joined it in folder phase 7). */
   place?: AcceptPlace;
 };
 
@@ -43,12 +43,18 @@ export type AcceptPlace = {
   /** The folder's crumbs, top-down, itself included. */
   crumbs: TreeCrumb[];
   creates: string[];
+  /** The share it is read at there through a shared folder (null: none):
+   *  the item is read at the more open of this and the chosen level. Absent
+   *  from brains before the Accept visibility check. */
+  share?: TreeShareLevel | null;
 };
 
 /** POST /api/team-admin/submissions/:id/accept and
  *  POST /api/admin/space/:id/accept. */
 export type AcceptRequest = {
   audience?: AccessLevel;
+  /** DEPRECATED (folder phase 7): pages do not nest; ignored. A page lands
+   *  like every tree kind (`folderId`). */
   parentPageId?: string | null;
   folderPath?: string | null;
   /** Where the item lands (folder plan phase 5): left out, in place; null,
@@ -61,6 +67,25 @@ export type AcceptRequest = {
    *  For a client's item at client or public every closure item that goes
    *  down must be here. */
   confirmedIds?: string[];
+  /** The admin saw the `visibility` refusal's list and accepts that those
+   *  items are read above the chosen level where they land. */
+  visibilityConfirmed?: boolean;
+};
+
+/** 409 from either Accept (brains with the Accept visibility check): the item, or something of its
+ *  bundle, lands in a shared folder and would be read above the chosen
+ *  level there. Nothing moved; repeat with `visibilityConfirmed: true`. */
+export type AcceptVisibilityRefusal = {
+  error: string;
+  reason: 'visibility';
+  /** The first changes (at most TREE_VISIBILITY_LIST_MAX): `from` the
+   *  chosen level, `to` the level it would be read at. */
+  changes: TreeVisibilityChange[];
+  total: number;
+  /** Brain items the bundle embeds that would be read through it at the
+   *  folder's share (migration 0208), `from` now, `to` then. Absent when
+   *  there are none, and from brains before it was listed. */
+  alsoEmbeds?: TreeVisibilityChange[];
 };
 
 /** 409 from either Accept: a client's item at client or public without the

package/src/dto/rows.ts

@@ -120,8 +120,10 @@ export type PageWidth = 'narrow' | 'wide';
 
 export type PageRow = {
   id: string;
-  /** Parent page id, or null for a top-level page. Drives the /pages tree
-   *  and the `childPage` card (Phase 4a sub-pages). */
+  /** DEPRECATED (folder phase 7): pages do not nest, so this is always
+   *  null. A page's place is its folder in the pages tree
+   *  (`GET /api/tree/pages`; `PageDetail.folderId`). Kept so a client from
+   *  before the tree, which built a hierarchy from it, still parses the row. */
   parentId: string | null;
   title: string;
   icon: string | null;
@@ -136,17 +138,14 @@ export type PageRow = {
 };
 
 /**
- * A row of the /pages LIST response (`GET /api/pages`): a `PageRow` plus where
- * it sits in the hierarchy. The list needs this per row because a search or tag
- * filter returns only the HITS, so the client cannot derive it from the rows it
- * holds: a hit's children and its parent are usually not among them.
+ * DEPRECATED (folder phase 7): `GET /api/pages` answers plain `PageRow`s.
+ * Pages do not nest, so nothing has sub-pages or a parent page any more; a
+ * client from before the tree reads `childCount` as 0 and `parentTitle` as
+ * null (both absent from the wire). Where a page sits is the pages tree's
+ * (`GET /api/tree/pages`).
  */
 export type PageListRow = PageRow & {
-  /** Direct sub-pages, counted across the whole hierarchy (not just this
-   *  response), so a search hit can offer the way into its sub-pages. */
   childCount: number;
-  /** The parent page's title, or null for a top-level page, so a hit can say
-   *  where it lives. */
   parentTitle: string | null;
 };
 
@@ -175,6 +174,13 @@ export type AppRow = {
   isHub: boolean;
   /** Access level (admin > team > client > public); the owner UI's badge. */
   audience: AccessLevel;
+  /** The share it inherits from a folder above it (team or client), or
+   *  null; it is read at the more open of this and `audience`. Optional:
+   *  absent from brains before the folder audit fixes. */
+  inherited?: 'team' | 'client' | null;
+  /** The share it is read at through something that embeds it (migration
+   *  0208), or null. Optional: absent from brains before it. */
+  embedded?: 'team' | 'client' | null;
   /** Informational (client logins C6): members and clients only read the
    *  app's data. Off, an app at team or client level is a shared workspace
    *  everyone who runs it writes. Set with PATCH /api/apps/:id

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
   AccessNodeUpdate,
   AccessNodeView,
   AccessSharedVia,
+  AccessReadThrough,
   ClientOldLinkAbove,
   ClientReport,
   ClientReportAck,
@@ -56,6 +57,7 @@ export type {
   AcceptPlace,
   AcceptPreview,
   AcceptRequest,
+  AcceptVisibilityRefusal,
   ReviewAuthorRole,
   ReviewAuthorView,
 } from './dto/review';

package/src/tree.ts

@@ -28,7 +28,7 @@ export const TREE_KINDS = [
   'contacts',
   'secrets',
   // Recall v2's maps (its own content type, not pages). Appended last so no
-  // earlier kind's index moves. Not served until the Recall screen ships.
+  // earlier kind's index moves. Served since the Recall screen (R3).
   'recall',
 ] as const;
 export type TreeKind = (typeof TREE_KINDS)[number];
@@ -160,11 +160,14 @@ export const TREE_KIND_SPECS: Readonly<Record<TreeKind, TreeKindSpec>> = {
   },
   // The tree lists maps only; a map's cards are recall_nodes rows, never
   // nodes, so they never appear as items.
+  // Not shareable YET: team sharing is Recall R6, which adds the recall root
+  // to nodes_share_level_ck and the type to mantle_workspace_kind(). Until
+  // then the database refuses the share, so the tree must not offer it.
   recall: {
     kind: 'recall',
     root: 'recall',
     nodeType: 'recall',
-    shareable: true,
+    shareable: false,
     shareLevels: ['team'],
     sorts: ['name', 'updated'],
   },
@@ -222,12 +225,16 @@ export type TreeItem = {
   /** A short kind-specific token for the status slot: a file's extension, a
    *  secret's kind, an event's start. Null when the kind has none. */
   subtype: string | null;
-  /** Who can read it: its own level, or its folder's share when that is more
-   *  open. */
+  /** Who can read it: the most open of its own level, its folder's share and
+   *  the share of something that embeds it. */
   level: AccessLevel;
   /** The share it takes from the nearest shared folder holding it (what
    *  "Shared via" names); null = none. `level` already counts it. */
   inherited?: TreeShareLevel | null;
+  /** The share it is read at through something that embeds it (a shared
+   *  note's image), kept by the brain; absent = none. `level` already
+   *  counts it. */
+  embedded?: TreeShareLevel | null;
   state: TreeItemState | null;
   updatedAt: string;
   meta?: TreeItemMeta;
@@ -299,6 +306,10 @@ export type TreeVisibilityChange = {
   title: string;
   from: AccessLevel;
   to: AccessLevel;
+  /** The item's node type ('file', 'table', 'note', 'branch', ...), sent in
+   *  `alsoEmbeds`: an embed may open any workspace item, and a table
+   *  opening is more than an image. Absent elsewhere. */
+  type?: string;
 };
 export type TreeVisibilityRefusal = {
   error: 'visibility';
@@ -306,6 +317,18 @@ export type TreeVisibilityRefusal = {
   changes: TreeVisibilityChange[];
   /** How many items change in all. */
   total: number;
+  /** Items elsewhere that pages, drawings and notes in `changes` embed,
+   *  whose access changes with them: `to` more open when they become
+   *  readable through them, less open when an unshare or a move out takes
+   *  that away (nothing's own level changes; migration 0208). Absent when
+   *  there are none, and from brains before it was listed. */
+  alsoEmbeds?: TreeVisibilityChange[];
+  /** How many embedded items change in all (`alsoEmbeds` holds the first
+   *  TREE_VISIBILITY_LIST_MAX). A confirm's `seen` is `total` plus this. */
+  embedsTotal?: number;
+  /** @deprecated Never sent: an unreleased first form of `alsoEmbeds`, when
+   *  a share still lowered embeds for good. */
+  alsoLowered?: TreeVisibilityChange[];
 };
 export const TREE_VISIBILITY_LIST_MAX = 100;
 
@@ -321,7 +344,10 @@ export const TREE_VISIBILITY_LIST_MAX = 100;
 /** A folder as a client login's tree shows it. */
 export type ClientTreeFolder = Omit<TreeFolder, 'share' | 'inherited' | 'system' | 'own'>;
 /** An item as a client login's tree shows it. */
-export type ClientTreeItem = Omit<TreeItem, 'level' | 'inherited' | 'state' | 'source' | 'author'>;
+export type ClientTreeItem = Omit<
+  TreeItem,
+  'level' | 'inherited' | 'embedded' | 'state' | 'source' | 'author'
+>;
 
 export type ClientTreeFolderPage = Omit<TreeFolderPage, 'folder' | 'folders' | 'items'> & {
   folder: ClientTreeFolder | null;

package/src/types/recall.ts

@@ -2,65 +2,37 @@
  * Wire shapes for the owner Recall API (roadmap tasks 073b322d / 91c93428;
  * docs/recall.md in the mantle repo). Dates are ISO strings.
  *
- * ── Two kinds of map ───────────────────────────────────────────────────────
- * v1 maps are COMPILED from a page tree: the rows are a build artifact, and a
- * card's `id` is its source page's node id, so every row is a click-through to
- * the page editor. v2 maps are NATIVE: the map is one `recall` item in the
- * tree, its cards are rows written directly, and a card's `id` is its own —
- * NOT a page. A client must not link a card to the page editor unless the map
- * is page-built, which `nodeId === null` tells it.
+ * A map is one `recall` item in the tree; its cards are rows written
+ * directly, and a card's `id` is its own, NOT a page. (Page-built v1 maps,
+ * compiled from a page tree, were retired in R5: the compile report, the
+ * page state route and `lastCompileOk` went with them.)
  *
  * Plan: "PLAN: Recall v2, its own content type" (dev brain, task 5d6ce06a).
- * Everything v2 adds here is additive, so a client written against the v1
- * shapes keeps compiling and keeps working against a v1 map.
  *
- * Whether a brain can serve the native path at all is `features.recallV2` from
- * `GET /api/shell`, absent on an older brain. Branch the SCREEN on that, not
- * on the shapes below.
+ * Whether a brain can serve Recall at all is `features.recallV2` from
+ * `GET /api/shell`, absent on a brain older than v2. Branch the SCREEN on
+ * that, not on the shapes below.
  */
 
-export type RecallLintSeverity = 'error' | 'warning';
-
-/** One issue from a map's last compile report (v1), or one warning from a
- *  native write (v2). */
-export interface RecallLintIssueDTO {
-  severity: RecallLintSeverity;
-  code: string;
-  message: string;
-  /** v1 only: the page the issue is about — the page-editor click-through. */
-  pageId?: string;
-  /** v2: the card the warning is about, by slug. A native map has no pages,
-   *  and a write that fails a CHECK is refused rather than reported here —
-   *  so on a native map these are only ever warnings (an orphan card, an
-   *  entry card with no options yet). */
-  cardSlug?: string;
-}
-
 /** One map in the catalog (`GET /api/recall/maps`). Unlike the agent-facing
- *  `recall_index`, the owner catalog includes never-compiled maps
- *  (`nodeCount` 0) — a failed compile is exactly what the owner must see. */
+ *  `recall_index`, the owner catalog includes unpublished maps and maps with
+ *  no cards yet. */
 export interface RecallMapSummaryDTO {
-  /** v1: the map root page's node id — a map IS its root page. v2: the map's
-   *  own id, which equals `nodeId`. Either way this is what the other Recall
+  /** The map's id, which equals `nodeId`. This is what the other Recall
    *  routes take as `:id`. */
   id: string;
   slug: string;
   title: string;
   /** The catalog line: when an agent should enter this map. */
   enterWhen: string;
-  /** Card count; 0 = a v1 map that never compiled clean. */
+  /** Card count. */
   nodeCount: number;
-  /** v1 only: false = the served rows are one rev behind the pages, and
-   *  `report` says why. Always true for a native map, which cannot be stale:
-   *  its rows are the source, and a write that fails its checks is refused. */
-  lastCompileOk: boolean;
-  /** v2: the map's `recall` item in the tree. NULL means this map is still
-   *  page-built, which is also the flag for "link its cards to the page
-   *  editor". */
-  nodeId: string | null;
+  /** The map's `recall` item in the tree. (It was null for a page-built map
+   *  before R5; a brain on R5 or later never serves one.) */
+  nodeId: string;
   /** v2: where the owner filed it, as display crumbs ("Mantle / Fleet");
-   *  null when unsorted or page-built. Derived from the item's folder, so it
-   *  is a label to show, never something to write back. */
+   *  null when unsorted. Derived from the item's folder, so it is a label to
+   *  show, never something to write back. */
   folder: string | null;
   /** v2: false while a map an AGENT created waits for the owner to publish
    *  it. An unpublished map is invisible to every agent-facing tool, so the
@@ -79,7 +51,7 @@ export interface RecallOptionDTO {
   /** Slug of the target card, within this map unless `targetMap` is set. */
   targetSlug: string;
   /** v2: the target card's id. Draw the graph from this, not from the slug —
-   *  it survives a rename. Absent on a v1-compiled row. */
+   *  it survives a rename. */
   targetId?: string;
   /** v2: a CROSS-MAP option. The slug of another published map, whose entry
    *  card this option leads to. Absent for an ordinary same-map edge. */
@@ -87,8 +59,7 @@ export interface RecallOptionDTO {
 }
 
 export interface RecallNodeDTO {
-  /** v1: the source page's node id, the page-editor click-through target.
-   *  v2: the card's own id. It is NOT a page — see the file header. */
+  /** The card's own id. It is NOT a page — see the file header. */
   id: string;
   slug: string;
   kind: 'index' | 'knowledge' | 'prompt';
@@ -100,8 +71,7 @@ export interface RecallNodeDTO {
    *  megabyte on the wire to render a sidebar. Fetch one card to edit it. */
   bodyChars: number;
   options: RecallOptionDTO[];
-  /** v1: the `pages.version` this row was compiled from. v2: the map version
-   *  the card was written at. */
+  /** The map version the card was written at. */
   sourceVersion: number;
   /** v2: the card's order in the editor. The list arrives sorted by it. */
   rank: number;
@@ -112,9 +82,9 @@ export interface RecallNodeDTO {
   updatedAt: string;
 }
 
-/** One card with its body — `GET /api/recall/maps/:id/cards/:cardId`, what
- *  the editor opens. Separate from the list shape on purpose (see
- *  `bodyChars`). */
+/** One card with its body, `GET /api/recall/maps/:id/cards/:slug`: what
+ *  the editor opens. A slug the card had before an explicit slug change still
+ *  finds it. Separate from the list shape on purpose (see `bodyChars`). */
 export interface RecallCardDetailDTO extends RecallNodeDTO {
   /** The markdown the owner edits, at most RECALL_BODY_CHAR_BUDGET characters
    *  (`@mantle/content-core/recall-compile`). */
@@ -128,29 +98,16 @@ export interface RecallCardDetailDTO extends RecallNodeDTO {
  *  write check must read the same constant, or the counter promises room the
  *  write refuses. */
 
-/** `GET /api/recall/maps/:id` — the whole compiled map, index node first,
- *  plus the last lint report (null when the last compile was clean). */
+/** `GET /api/recall/maps/:id` — the whole map, its cards in rank order
+ *  (the entry card is rank 0). */
 export interface RecallMapDetailDTO extends RecallMapSummaryDTO {
-  report: RecallLintIssueDTO[] | null;
   nodes: RecallNodeDTO[];
 }
 
-/** `GET /api/recall/pages/:id` — this page's place in Recall, if any. Backs
- *  the editor lint badge: the compiler never blocks a commit, so this badge
- *  is the ONLY place an author learns the map is serving a stale rev.
- *  `node` is null when the page is named in a failing report but has no
- *  compiled row yet (a brand-new page that broke the map). */
-export interface RecallPageStateDTO {
-  map: RecallMapSummaryDTO;
-  node: { slug: string; kind: RecallNodeDTO['kind'] } | null;
-  report: RecallLintIssueDTO[] | null;
-}
-
 // ── v2: the write side ───────────────────────────────────────────────────────
 // The owner routes the Recall editor calls. Every write carries the map
 // `version` it was made against; a stale one is refused rather than silently
-// overwriting another editor's (or an agent's) change. Nothing here exists on
-// a v1 map: the page editor is its authoring surface.
+// overwriting another editor's (or an agent's) change.
 
 /** Who made a change. An `agent` row is why the revision log exists: v2 serves
  *  an agent's card edit immediately, with no compile step to hold it back. */
@@ -179,8 +136,10 @@ export interface RecallMapCreateResultDTO {
 /** The body of every refused Recall write. `error` is a sentence written to be
  *  shown as is: what failed and what to do. `code` is stable and absent only on
  *  a malformed request (a body that failed validation). A stale `version` is
- *  409 with code `version_stale`; any code ending `_not_found` is 404; every
- *  other refusal is 400. */
+ *  409 with code `version_stale`; `map_not_found`, `card_not_found` and
+ *  `revision_not_found` are 404; every other refusal is 400, including a bad
+ *  reference inside the body (`cross_map_not_found`, `folder_not_found`) and a
+ *  revision that has nothing to put back (`revision_not_restorable`). */
 export interface RecallWriteErrorDTO {
   error: string;
   code?: string;
@@ -199,28 +158,44 @@ export interface RecallMapPatchDTO {
   version: number;
 }
 
-/** `PUT /api/recall/maps/:id/cards/:cardId` — create or replace one card.
- *  `options` replaces the card's whole list, so read-modify-write it. */
+/** A card write. `POST /api/recall/maps/:id/cards` adds one;
+ *  `PUT /api/recall/maps/:id/cards/:slug` replaces an existing one (an unknown
+ *  slug is 404, not a create).
+ *
+ *  `title` and `bodyMd` always replace. `useWhen`, `options` and `prompt` are
+ *  STICKY on a replace: leave one out and the card keeps its value. So send
+ *  `prompt` only when the owner changed the Prompt switch: a save that sends
+ *  `prompt: false` for a card with a pending request drops the request. When
+ *  `options` is sent it replaces the card's whole list: read-modify-write it. */
 export interface RecallCardWriteDTO {
   title: string;
   /** Markdown, at most RECALL_BODY_CHAR_BUDGET characters. */
   bodyMd: string;
-  /** The matcher line. Required when `prompt` is true: a prompt without one
-   *  cannot be matched by meaning, which is the only thing prompts are for. */
+  /** The matcher line. Required when the card is or asks to be a prompt: a
+   *  prompt without one cannot be matched by meaning, which is the only thing
+   *  prompts are for. */
   useWhen?: string;
-  /** Ask for this card to be a prompt. From the OWNER this makes it one; from
-   *  an agent it only records the request (`promptPending`). */
+  /** From the OWNER: true makes the card a prompt (confirming any pending
+   *  request), false makes it knowledge (demoting a prompt, or dropping a
+   *  request). From an agent, true only records a request (`promptPending`). */
   prompt?: boolean;
   options?: RecallOptionDTO[];
-  /** Slug of the card to place this one after, for a new card. */
+  /** POST only: the slug of the card to place the new one after. A slug that
+   *  names no card is refused (`after_not_found`). */
   after?: string;
+  /** PUT only, owner only: an explicit slug change. The old slug keeps
+   *  resolving (recall_go, the card GET), and options in this map that led to
+   *  it follow the card. */
+  slug?: string;
   version: number;
 }
 
 /** One advisory warning from a native write. Never blocks: an orphan card is
  *  a normal intermediate state while a map is being built. No `severity`,
  *  because a native write has only one kind of issue it reports rather than
- *  refuses. Codes today: `orphan_card`, `entry_without_options`. */
+ *  refuses. Codes today: `orphan_card`, `entry_without_options`,
+ *  `cross_map_target_gone` (an option to a map no longer published, hidden
+ *  from agents), `prompt_kept` (an agent tried to demote a prompt). */
 export interface RecallWarningDTO {
   code: string;
   message: string;
@@ -242,7 +217,13 @@ export interface RecallWriteResultDTO {
 }
 
 /** One entry in a map's revision log (`GET /api/recall/maps/:id/revisions`),
- *  newest first. Restore one with `POST /api/recall/revisions/:id/restore`. */
+ *  newest first. Restore one with `POST /api/recall/revisions/:id/restore`,
+ *  which puts back what that write replaced: a card's content (and its slug,
+ *  if that write moved it); a deleted card under its old slug, at its old
+ *  place, with the options other cards had to it; the old order for a
+ *  reorder; the map fields that write changed. Undoing "card added" deletes
+ *  the card. "map created" cannot be restored (`revision_not_restorable`), nor
+ *  can a reorder logged before its old order was kept. */
 export interface RecallRevisionDTO {
   id: string;
   /** The card this touched; null for a map-level change. */
@@ -250,9 +231,12 @@ export interface RecallRevisionDTO {
   /** The card's slug at the time, for display when the card is gone. */
   cardSlug: string | null;
   actorKind: RecallActorKind;
-  /** The agent's slug or the admin's display name, when known. */
+  /** The agent's slug, 'mcp' for an external MCP client, or the admin's
+   *  display name, stored with the revision. Null on rows written before
+   *  brain v0.232.357. */
   actorName: string | null;
-  /** One line on what changed ("body edited", "card added", "published"). */
+  /** One line on what changed: "card added", "card edited", "card deleted",
+   *  "cards reordered", "prompt confirmed", "renamed, published", and so on. */
   summary: string;
   createdAt: string;
 }