@crossworks/client-types 0.232.351 → 0.232.354

package/package.json

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

package/src/dto/access.ts

@@ -74,6 +74,19 @@ export type AccessNodeView = {
   /** Old live links above this item (see ClientOldLinkAbove); only for an
    *  item at client. */
   oldLinksAbove?: ClientOldLinkAbove[];
+  /** The shared folder it takes its share from (folder sharing); null when
+   *  none. Absent from brains before folder sharing. */
+  sharedVia?: AccessSharedVia | null;
+};
+
+/** The nearest shared folder holding an item (folder sharing, phase 4). The
+ *  item is read at least at `level`, whatever its own level says, so the
+ *  control offers nothing above it: moving it out of the folder hides it. */
+export type AccessSharedVia = {
+  folderId: string;
+  /** Folder names from the kind's top level down to the shared folder. */
+  trail: string[];
+  level: 'team' | 'client';
 };
 
 /** One item that went down with the item that embeds it. */

package/src/dto/client.ts

@@ -8,6 +8,7 @@
 import type { ClientItemKind, MemberItemKind } from '../member-kinds';
 import type { MemberItemPill, MemberSpaceItemRow } from './member';
 import type { NodeComment } from './rows';
+import type { TreeKind } from '../tree';
 
 /** GET /api/client/shell: who is signed in and the brain's brand. */
 export type ClientShell = {
@@ -29,6 +30,10 @@ export type ClientShell = {
   fontProseSize: string | null;
   logoVersion: string | null;
   logoDarkVersion: string | null;
+  /** The kinds this login browses as a read-only folder tree (GET
+   *  /api/{member,client}/tree/:kind). Absent from brains before folder
+   *  sharing: the client keeps its flat lists there. */
+  treeKinds?: TreeKind[];
 };
 
 /** One item in "Shared with you": an item at client level. */

package/src/dto/member.ts

@@ -6,6 +6,7 @@
  */
 import type { AccessLevel, MemberItemAuthor } from './access';
 import type { MemberItemKind } from '../member-kinds';
+import type { TreeKind } from '../tree';
 export type { MemberItemFilter } from '../member-kinds';
 
 /** GET /api/member/shell */
@@ -30,6 +31,10 @@ export type MemberShell = {
   fontProseSize: string | null;
   logoVersion: string | null;
   logoDarkVersion: string | null;
+  /** The kinds this login browses as a read-only folder tree (GET
+   *  /api/{member,client}/tree/:kind). Absent from brains before folder
+   *  sharing: the client keeps its flat lists there. */
+  treeKinds?: TreeKind[];
 };
 
 export type MemberLibraryKind = MemberItemKind;
@@ -219,6 +224,10 @@ export type MemberAcceptedRow = {
   icon: string | null;
   /** The level the admin chose: at team or lower it is in the Library too. */
   audience: AccessLevel;
+  /** The share it takes from a folder holding it: in the Library at that
+   *  level too, whatever `audience` says. Absent from brains before folder
+   *  sharing. */
+  inherited?: 'team' | 'client' | null;
   acceptedAt: string | null;
   updatedAt: string;
 };

package/src/dto/recall.ts

@@ -11,11 +11,21 @@
 // ── Recall (memory maps) ─────────────────────────────────────────────────────
 
 export type {
+  RecallActorKind,
+  RecallCardDetailDTO,
+  RecallCardWriteDTO,
   RecallLintIssueDTO,
   RecallLintSeverity,
+  RecallMapCreateDTO,
+  RecallMapCreateResultDTO,
   RecallMapDetailDTO,
+  RecallMapPatchDTO,
   RecallMapSummaryDTO,
   RecallNodeDTO,
   RecallOptionDTO,
   RecallPageStateDTO,
+  RecallRevisionDTO,
+  RecallWarningDTO,
+  RecallWriteErrorDTO,
+  RecallWriteResultDTO,
 } from '../types/recall';

package/src/dto/review.ts

@@ -5,6 +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';
 
 /** Who wrote a reviewable item: a member or a client login. */
 export type ReviewAuthorRole = 'member' | 'client';
@@ -29,6 +30,19 @@ export type AcceptPreview = {
    *  CURRENT level. The client shows the ones above the chosen level: they
    *  go DOWN with it and need a tick. */
   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. */
+  place?: AcceptPlace;
+};
+
+export type AcceptPlace = {
+  kind: TreeKind;
+  folderId: string | null;
+  /** The folder's crumbs, top-down, itself included. */
+  crumbs: TreeCrumb[];
+  creates: string[];
 };
 
 /** POST /api/team-admin/submissions/:id/accept and
@@ -37,6 +51,10 @@ export type AcceptRequest = {
   audience?: AccessLevel;
   parentPageId?: string | null;
   folderPath?: string | null;
+  /** Where the item lands (folder plan phase 5): left out, in place; null,
+   *  the kind's top level; an id, a brain folder of its kind (the author's
+   *  own folders still go below it). The rest of the bundle lands in place. */
+  folderId?: string | null;
   /** A client's item at client or public: the admin confirmed the level. */
   lowerConfirmed?: boolean;
   /** Ids of closure items the admin ticked (with `lowerConfirmed: true`).

package/src/index.ts

@@ -40,6 +40,7 @@ export type {
   AccessLoweredView,
   AccessNodeUpdate,
   AccessNodeView,
+  AccessSharedVia,
   ClientOldLinkAbove,
   ClientReport,
   ClientReportAck,
@@ -52,6 +53,7 @@ export type {
 } from './dto/access';
 export type {
   AcceptConfirmLevelRefusal,
+  AcceptPlace,
   AcceptPreview,
   AcceptRequest,
   ReviewAuthorRole,
@@ -171,3 +173,26 @@ export type {
   AppOpenStat,
   AppTint,
 } from './app-nav';
+
+// Types only at the root; the runtime constants (kinds, specs, limits) are the
+// `@mantle/client-types/tree` subpath.
+export type {
+  ClientTreeFolder,
+  ClientTreeFolderPage,
+  ClientTreeItem,
+  ClientTreeSearchResult,
+  TreeCrumb,
+  TreeFolder,
+  TreeFolderPage,
+  TreeItem,
+  TreeItemState,
+  TreeKind,
+  TreeKindSpec,
+  TreeMarkList,
+  TreeMarkView,
+  TreeSearchResult,
+  TreeShareLevel,
+  TreeSort,
+  TreeVisibilityChange,
+  TreeVisibilityRefusal,
+} from './tree';

package/src/tree.ts

@@ -0,0 +1,337 @@
+/**
+ * The item tree: one navigation for every workspace kind (docs/folder-tree.md).
+ *
+ * A kind's items live under the kind's root (`files`, `notes`, ...). Folders
+ * are `branch` rows under that root and nest at most TREE_MAX_DEPTH deep; an
+ * item's location is its folder's path, and an item at the root is unsorted.
+ * Items are never parents. Every reader (admin, member, client) browses the
+ * same tree, pruned by the brain to what that reader may see.
+ *
+ * Pure (no runtime deps) so the brain and every client share the kinds, the
+ * limits and the wire shapes. A runtime constant module, so it is the
+ * `@mantle/client-types/tree` subpath.
+ */
+import type { AccessLevel } from './dto/access';
+import type { AppTint } from './app-nav';
+
+/** The kinds the tree serves, in navigation order. */
+export const TREE_KINDS = [
+  'files',
+  'notes',
+  'pages',
+  'draw',
+  'tables',
+  'formulas',
+  'apps',
+  'tasks',
+  'events',
+  '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.
+  'recall',
+] as const;
+export type TreeKind = (typeof TREE_KINDS)[number];
+
+export function isTreeKind(v: unknown): v is TreeKind {
+  return typeof v === 'string' && (TREE_KINDS as readonly string[]).includes(v);
+}
+
+/** Folders nest at most this deep below a kind's root: folder › subfolder ›
+ *  sub-subfolder. Items sit in any of them. */
+export const TREE_MAX_DEPTH = 3;
+/** Items per folder page; the client asks for the next page as it scrolls. */
+export const TREE_PAGE_SIZE = 50;
+export const TREE_PAGE_MAX = 100;
+export const TREE_FOLDER_NAME_MAX = 60;
+export const TREE_SEARCH_MAX = 200;
+
+/** The orders a folder's items can be listed in. Folders always keep their
+ *  own manual order (rank, then name). */
+export const TREE_SORTS = ['name', 'updated', 'start', 'due'] as const;
+export type TreeSort = (typeof TREE_SORTS)[number];
+
+export function isTreeSort(v: unknown): v is TreeSort {
+  return typeof v === 'string' && (TREE_SORTS as readonly string[]).includes(v);
+}
+
+/** Who a shared folder shares its contents with. Public is never a folder
+ *  share: an item goes public through its own link. */
+export const TREE_SHARE_LEVELS = ['team', 'client'] as const;
+export type TreeShareLevel = (typeof TREE_SHARE_LEVELS)[number];
+
+/** Everything that differs between kinds, in one place. The brain adds its
+ *  own hooks (the files disk mirror); a client reads the rest. */
+export type TreeKindSpec = {
+  kind: TreeKind;
+  /** The ltree root label of the kind (the `*_ROOT_LABEL` constants). */
+  root: string;
+  /** `nodes.type` of the kind's items. */
+  nodeType: string;
+  /** Whether a folder of this kind may be shared below admin. The kinds that
+   *  are admin-only forever (the type ceiling) never are. */
+  shareable: boolean;
+  /** The item orders offered, the first being the default. */
+  sorts: readonly TreeSort[];
+  /** Which levels a folder of this kind may be shared at. Absent means both
+   *  of TREE_SHARE_LEVELS. Recall is team-only: a client agent matching the
+   *  owner's prompts is the case the Recall v1 plan deferred. Enforced where
+   *  folders are shared (phase 4). */
+  shareLevels?: readonly TreeShareLevel[];
+};
+
+export const TREE_KIND_SPECS: Readonly<Record<TreeKind, TreeKindSpec>> = {
+  files: {
+    kind: 'files',
+    root: 'files',
+    nodeType: 'file',
+    shareable: true,
+    sorts: ['name', 'updated'],
+  },
+  notes: {
+    kind: 'notes',
+    root: 'notes',
+    nodeType: 'note',
+    shareable: true,
+    sorts: ['updated', 'name'],
+  },
+  pages: {
+    kind: 'pages',
+    root: 'pages',
+    nodeType: 'page',
+    shareable: true,
+    sorts: ['updated', 'name'],
+  },
+  draw: {
+    kind: 'draw',
+    root: 'draw',
+    nodeType: 'draw',
+    shareable: true,
+    sorts: ['updated', 'name'],
+  },
+  tables: {
+    kind: 'tables',
+    root: 'tables',
+    nodeType: 'table',
+    shareable: true,
+    sorts: ['updated', 'name'],
+  },
+  formulas: {
+    kind: 'formulas',
+    root: 'formulas',
+    nodeType: 'formula',
+    shareable: true,
+    sorts: ['name', 'updated'],
+  },
+  apps: {
+    kind: 'apps',
+    root: 'apps',
+    nodeType: 'app',
+    shareable: true,
+    sorts: ['name', 'updated'],
+  },
+  tasks: {
+    kind: 'tasks',
+    root: 'tasks',
+    nodeType: 'task',
+    shareable: false,
+    sorts: ['due', 'updated', 'name'],
+  },
+  events: {
+    kind: 'events',
+    root: 'events',
+    nodeType: 'event',
+    shareable: false,
+    sorts: ['start', 'name'],
+  },
+  contacts: {
+    kind: 'contacts',
+    root: 'contacts',
+    nodeType: 'contact',
+    shareable: false,
+    sorts: ['name', 'updated'],
+  },
+  secrets: {
+    kind: 'secrets',
+    root: 'secrets',
+    nodeType: 'secret',
+    shareable: false,
+    sorts: ['name', 'updated'],
+  },
+  // The tree lists maps only; a map's cards are recall_nodes rows, never
+  // nodes, so they never appear as items.
+  recall: {
+    kind: 'recall',
+    root: 'recall',
+    nodeType: 'recall',
+    shareable: true,
+    shareLevels: ['team'],
+    sorts: ['name', 'updated'],
+  },
+};
+
+/** One folder as the tree shows it. Counts are what THIS reader can see. */
+export type TreeFolder = {
+  id: string;
+  /** The folder's ltree path: its identity in agent tools and on disk. */
+  path: string;
+  name: string;
+  /** An emoji or `lucide:<name>` (the app-nav icon vocabulary); null = the
+   *  default folder glyph. */
+  icon: string | null;
+  color: AppTint | null;
+  /** 1..TREE_MAX_DEPTH below the kind's root. */
+  depth: number;
+  /** The parent folder; null at the top level. */
+  parentId: string | null;
+  /** The folder's own share (it shares everything below it); null = none. */
+  share: TreeShareLevel | null;
+  /** The share of the nearest shared folder above it; null = none. */
+  inherited?: TreeShareLevel | null;
+  /** Made by Mantle (Auto-filed): the name is locked and it cannot be shared. */
+  system: boolean;
+  folderCount: number;
+  itemCount: number;
+  /** A member's tree only: the member's own private folder (folder plan
+   *  phase 5). Only they see it; they may rename, move and delete it. */
+  own?: boolean;
+};
+
+/** An item's review state, when it has one (the one-list pill vocabulary). */
+export type TreeItemState = 'private' | 'draft' | 'submitted' | 'returned' | 'with-admin';
+
+/** Kind-specific facts a row draws: a task's done box and due date, an
+ *  event's start. Only the kinds that have them send them. */
+export type TreeItemMeta = {
+  /** A task marked done. */
+  done?: boolean;
+  /** A task's due instant (ISO), when it has one. */
+  due?: string | null;
+  /** An event's start (ISO). */
+  start?: string | null;
+};
+
+/** One item as the tree shows it: a title and what the status slot needs.
+ *  Summaries, descriptions and tags live in the item's own view. */
+export type TreeItem = {
+  id: string;
+  title: string;
+  /** The item's own icon when it has one (emoji or lucide key). */
+  icon: string | null;
+  color: AppTint | null;
+  /** 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. */
+  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;
+  state: TreeItemState | null;
+  updatedAt: string;
+  meta?: TreeItemMeta;
+  /** A member's tree only: a draft rather than a brain item (folder plan
+   *  phase 5). `own` is the member's own; `team` a teammate's draft shared
+   *  with the team. Absent on a brain item. */
+  source?: 'own' | 'team';
+  /** A teammate's draft: who wrote it. */
+  author?: string;
+};
+
+export type TreeCrumb = { id: string; name: string };
+
+/** GET /api/tree/:kind?folder= — one folder's direct subfolders (all, in
+ *  order) and one page of its items. `folder` null is the kind's root. */
+export type TreeFolderPage = {
+  kind: TreeKind;
+  folder: TreeFolder | null;
+  /** Top-down, excluding `folder` itself. */
+  crumbs: TreeCrumb[];
+  folders: TreeFolder[];
+  items: TreeItem[];
+  sort: TreeSort;
+  /** Pass back as `cursor` for the next page of items; null at the end. */
+  nextCursor: string | null;
+};
+
+/** Narrowing for GET /api/tree/:kind/search (`level=`, `tag=`), the tree's
+ *  filter menu. Both optional; together they both apply. A filtered search
+ *  lists items only, no folders. */
+export type TreeFilter = {
+  /** Only items read at this level (their own, or their folder's share). */
+  level?: AccessLevel;
+  /** Only items carrying this tag. */
+  tag?: string;
+};
+export const TREE_TAG_MAX = 100;
+
+/** GET /api/tree/:kind/tags — the tags on a kind's items, most used first,
+ *  for the filter menu. At most TREE_TAGS_LIST_MAX. */
+export type TreeTagList = { kind: TreeKind; tags: Array<{ tag: string; count: number }> };
+export const TREE_TAGS_LIST_MAX = 40;
+
+/** GET /api/tree/:kind/search?q= — matching folders first, then items, each
+ *  with the crumbs of where it lives. */
+export type TreeSearchResult = {
+  kind: TreeKind;
+  folders: Array<TreeFolder & { crumbs: TreeCrumb[] }>;
+  items: Array<TreeItem & { crumbs: TreeCrumb[] }>;
+  nextCursor: string | null;
+};
+
+/** The flat views beside the tree: this login's pins, recent and most used
+ *  items of a kind. */
+export const TREE_MARK_VIEWS = ['pinned', 'recent', 'used'] as const;
+export type TreeMarkView = (typeof TREE_MARK_VIEWS)[number];
+export const TREE_PINS_MAX = 12;
+
+export type TreeMarkList = {
+  kind: TreeKind;
+  view: TreeMarkView;
+  items: Array<TreeItem & { crumbs: TreeCrumb[] }>;
+};
+
+/** A write that would change who can see something is refused with this
+ *  (409) until it is repeated with `confirm: true`. */
+export type TreeVisibilityChange = {
+  id: string;
+  title: string;
+  from: AccessLevel;
+  to: AccessLevel;
+};
+export type TreeVisibilityRefusal = {
+  error: 'visibility';
+  /** The first changes (at most TREE_VISIBILITY_LIST_MAX). */
+  changes: TreeVisibilityChange[];
+  /** How many items change in all. */
+  total: number;
+};
+export const TREE_VISIBILITY_LIST_MAX = 100;
+
+// ── The member and client trees ──────────────────────────────────────────
+// A member (team) or client login browses the kinds its Library holds as a
+// read-only tree: GET /api/member/tree/:kind and /api/client/tree/:kind (with
+// /search), the kinds its shell lists in `treeKinds`. A member receives the
+// shapes above (levels are staff information); a client receives these,
+// which carry no level, share or system flag (clients see the brand, not the
+// staff view). Folders show where the reader reads something below them or
+// where a folder's share covers the reader; counts are the reader's.
+
+/** 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 ClientTreeFolderPage = Omit<TreeFolderPage, 'folder' | 'folders' | 'items'> & {
+  folder: ClientTreeFolder | null;
+  folders: ClientTreeFolder[];
+  items: ClientTreeItem[];
+};
+
+export type ClientTreeSearchResult = {
+  kind: TreeKind;
+  folders: Array<ClientTreeFolder & { crumbs: TreeCrumb[] }>;
+  items: Array<ClientTreeItem & { crumbs: TreeCrumb[] }>;
+  nextCursor: string | null;
+};

package/src/types/recall.ts

@@ -1,65 +1,133 @@
 /**
- * Wire shapes for the owner Recall API (`GET /api/recall/maps`,
- * `GET /api/recall/maps/:id`) — the read side of the Recall UI (roadmap
- * tasks 073b322d / 91c93428; docs/recall.md in the mantle repo).
+ * Wire shapes for the owner Recall API (roadmap tasks 073b322d / 91c93428;
+ * docs/recall.md in the mantle repo). Dates are ISO strings.
  *
- * These describe the COMPILED serving layer (recall_maps / recall_nodes),
- * not the source pages: node `id` is the source page's node id, so every
- * row is a click-through to the page editor. 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.
+ *
+ * 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.
  */
 
 export type RecallLintSeverity = 'error' | 'warning';
 
-/** One issue from a map's last compile report. */
+/** 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;
-  /** The page the issue is about — the editor click-through target. */
+  /** 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. */
 export interface RecallMapSummaryDTO {
-  /** The map root page's node id — a map IS its root page. */
+  /** 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
+   *  routes take as `:id`. */
   id: string;
   slug: string;
   title: string;
   /** The catalog line: when an agent should enter this map. */
   enterWhen: string;
-  /** Compiled node count; 0 = never compiled clean. */
+  /** Card count; 0 = a v1 map that never compiled clean. */
   nodeCount: number;
-  /** False = the served rows are one rev behind the pages; `report` says why. */
+  /** 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;
+  /** 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. */
+  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
+   *  owner UI is the only place it can be seen — show it as a draft. */
+  published: boolean;
+  /** v2: optimistic-concurrency token. Send it back on a write; a stale one
+   *  is refused rather than silently overwriting someone else's edit. */
+  version: number;
   updatedAt: string;
 }
 
-/** One routing edge as compiled: an affordance ("use when …"), never a command. */
+/** One routing edge: an affordance ("use when …"), never a command. */
 export interface RecallOptionDTO {
   label: string;
   useWhen: string;
-  /** Slug of the target node within the same map. */
+  /** 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. */
+  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. */
+  targetMap?: string;
 }
 
 export interface RecallNodeDTO {
-  /** The source page's node id — the editor click-through target. */
+  /** 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. */
   id: string;
   slug: string;
   kind: 'index' | 'knowledge' | 'prompt';
   title: string;
   /** Prompts: the matcher line; empty elsewhere. */
   useWhen: string;
-  /** Rendered-markdown body size (the budget is enforced at compile). */
+  /** Body size in characters (the budget is enforced on the write). The body
+   *  itself is not in the list shape: a 100-card map would put most of a
+   *  megabyte on the wire to render a sidebar. Fetch one card to edit it. */
   bodyChars: number;
   options: RecallOptionDTO[];
-  /** `pages.version` this row was compiled from — staleness at a glance. */
+  /** v1: the `pages.version` this row was compiled from. v2: 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;
+  /** v2: an AGENT asked for this card to be a prompt and the owner has not
+   *  confirmed. Until they do it is not embedded and never matches, so show
+   *  it as a request rather than as a prompt. */
+  promptPending: boolean;
   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`). */
+export interface RecallCardDetailDTO extends RecallNodeDTO {
+  /** The markdown the owner edits, at most RECALL_BODY_CHAR_BUDGET characters
+   *  (`@mantle/content-core/recall-compile`). */
+  bodyMd: string;
+}
+
+/** The caps a card and a map are held to are NOT redefined here: they already
+ *  live in `@mantle/content-core/recall-compile`, which clients also consume —
+ *  `RECALL_BODY_CHAR_BUDGET` (6000 characters of body) and
+ *  `RECALL_MAX_MAP_NODES` (100 cards). The editor's counter and the brain's
+ *  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). */
 export interface RecallMapDetailDTO extends RecallMapSummaryDTO {
@@ -77,3 +145,114 @@ export interface RecallPageStateDTO {
   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.
+
+/** 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. */
+export type RecallActorKind = 'owner' | 'agent';
+
+/** `POST /api/recall/maps` — a new map, with its entry card. Created
+ *  unpublished when an agent asks; the owner publishes it. */
+export interface RecallMapCreateDTO {
+  title: string;
+  /** The catalog line: when an agent should enter this map. */
+  enterWhen: string;
+  /** Folder crumbs to file it under ("Mantle / Fleet"), or omit for unsorted.
+   *  Folders must already exist; this does not create them. */
+  folder?: string;
+}
+
+/** `POST /api/recall/maps` answers 201 with this. An owner-created map is
+ *  published at once; only an agent's starts as a draft. */
+export interface RecallMapCreateResultDTO {
+  mapId: string;
+  slug: string;
+  version: number;
+  published: boolean;
+}
+
+/** 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. */
+export interface RecallWriteErrorDTO {
+  error: string;
+  code?: string;
+}
+
+/** `PATCH /api/recall/maps/:id` — only the fields present are changed.
+ *  Renaming does NOT change the slug: agents and skills remember slugs. */
+export interface RecallMapPatchDTO {
+  title?: string;
+  enterWhen?: string;
+  /** An explicit slug change. The old slug is kept and keeps resolving. */
+  slug?: string;
+  /** Publish (or unpublish) the map. Publishing is what makes it visible to
+   *  every agent-facing tool. */
+  published?: boolean;
+  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. */
+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. */
+  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`). */
+  prompt?: boolean;
+  options?: RecallOptionDTO[];
+  /** Slug of the card to place this one after, for a new card. */
+  after?: 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`. */
+export interface RecallWarningDTO {
+  code: string;
+  message: string;
+  /** The card the warning is about, when it is about one. */
+  cardSlug?: string;
+}
+
+/** What a write answers with. */
+export interface RecallWriteResultDTO {
+  /** The map's new version. Carry it into the next write. */
+  version: number;
+  /** The slug of the card written, absent for a map-level write. The body is
+   *  not echoed back: GET the card if the editor needs it again. */
+  cardSlug?: string;
+  warnings: RecallWarningDTO[];
+  /** Cards whose options pointed at a card this write deleted, and so had
+   *  that option removed in the same transaction. */
+  optionsDropped?: { cardSlug: string; label: string }[];
+}
+
+/** 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`. */
+export interface RecallRevisionDTO {
+  id: string;
+  /** The card this touched; null for a map-level change. */
+  cardId: string | null;
+  /** 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. */
+  actorName: string | null;
+  /** One line on what changed ("body edited", "card added", "published"). */
+  summary: string;
+  createdAt: string;
+}