@lambdacurry/arbor 0.24.34 → 0.24.36

package/dist/arbor.js

@@ -6955,6 +6955,7 @@ function json(params) {
   return jsonSchema;
 }
 // ../core/src/objects/types.ts
+var TOPIC_LIFECYCLES = ["planned", "open", "on-hold", "closed", "archived"];
 var IDENTITY_COLORS = [
   "indigo",
   "teal",
@@ -8562,6 +8563,7 @@ var topics = sqliteTable("topics", {
   workflowId: text("workflow_id"),
   visibility: text("visibility").$type().notNull().default("open"),
   ownerProfileId: text("owner_profile_id").references(() => profiles.id),
+  lifecycle: text("lifecycle").$type().notNull().default("open"),
   archivedAt: ts("archived_at"),
   createdAt: ts("created_at").notNull()
 }, (t) => ({
@@ -10217,6 +10219,9 @@ var ORG_ADMIN_CONTAINMENT_PERMISSIONS = new Set([
   "revoke"
 ]);
 
+// ../core/src/ops/topic-lifecycle.ts
+var INITIAL_TOPIC_LIFECYCLES = ["planned", "open"];
+
 // ../core/src/queries/artifact-base.ts
 var eventChronology = sql`_rowid_`;
 var SPACE_ARTIFACT_STATUSES = [
@@ -11121,13 +11126,17 @@ function buildOutputSchemas() {
     type: string2(),
     description: string2().optional()
   });
+  const topicLifecycle = _enum(TOPIC_LIFECYCLES);
+  const removedTopicStatus = never().optional();
   const topic = looseObject({
     id,
     spaceId: id.optional(),
     title: string2(),
     purpose: nullableString.optional(),
     url: string2().optional(),
-    workflowId: nullableString.optional()
+    workflowId: nullableString.optional(),
+    lifecycle: topicLifecycle.optional(),
+    status: removedTopicStatus
   });
   const space = looseObject({
     id,
@@ -11285,7 +11294,8 @@ function buildOutputSchemas() {
     purpose: string2().optional(),
     threadCount: number2(),
     activeThreadCount: number2(),
-    status: _enum(["healthy", "attention", "stuck"]),
+    lifecycle: topicLifecycle,
+    status: removedTopicStatus,
     openRequestCount: number2().optional(),
     lastActivityAt: timestamp,
     lanesForYou: array(string2()).optional(),
@@ -11437,13 +11447,19 @@ function buildOutputSchemas() {
       reacted: boolean2(),
       reactions: array(reactionCount)
     }),
-    create_topic: looseObject({ topicId: id, url: string2().optional() }),
+    create_topic: looseObject({
+      topicId: id,
+      url: string2().optional(),
+      lifecycle: topicLifecycle.optional()
+    }),
     topic_update: looseObject({
       id,
       title: string2().optional(),
       purpose: nullableString.optional(),
       workflowId: nullableString.optional(),
-      visibility: _enum(["open", "private"]).optional()
+      visibility: _enum(["open", "private"]).optional(),
+      lifecycle: topicLifecycle.optional(),
+      archivedAt: nullableString.optional()
     }),
     create_thread: looseObject({ threadId: id, url: string2().optional() }),
     thread_update: looseObject({
@@ -11723,7 +11739,8 @@ function buildOutputSchemas() {
     }),
     space_get: looseObject({
       space,
-      topics: array(topic).optional(),
+      topics: array(topic.extend({ lifecycle: topicLifecycle })).optional(),
+      archivedTopics: array(looseObject({ id, title: string2(), lifecycle: literal("archived") })).optional(),
       members: array(member).optional(),
       total: number2().int().min(0),
       nextCursor: string2().optional(),
@@ -11732,7 +11749,8 @@ function buildOutputSchemas() {
       defaultWorkflow: workflowSummary.optional()
     }),
     topic_get: looseObject({
-      topic,
+      topic: topic.extend({ lifecycle: topicLifecycle }),
+      lifecycleChoices: array(topicLifecycle).optional(),
       space,
       workflow: workflowSummary.optional(),
       threads: array(thread).optional(),
@@ -12025,6 +12043,46 @@ function buildOutputSchemas() {
           serializedByteLimit: number2().int().positive()
         })
       }),
+      presence: discriminatedUnion("status", [
+        object({ status: literal("absent") }).strict(),
+        object({ status: literal("unavailable") }).strict(),
+        looseObject({
+          status: literal("present"),
+          sessions: number2().int().positive(),
+          pageId: string2().nullable(),
+          viewport: jsonObject.nullable(),
+          lastActiveAt: timestamp.nullable(),
+          selection: looseObject({
+            shapeIds: array(string2()),
+            shapes: array(jsonObject),
+            missingShapeIds: array(string2()),
+            clusterIds: array(string2()),
+            bounds: jsonObject.nullable()
+          })
+        })
+      ]).optional(),
+      comments: looseObject({
+        items: array(looseObject({
+          contributionId: id,
+          url: string2(),
+          author: jsonObject,
+          createdAt: timestamp,
+          text: string2(),
+          anchor: jsonObject,
+          replyCount: number2().int().nonnegative(),
+          replies: array(jsonObject)
+        })),
+        total: number2().int().nonnegative(),
+        omitted: number2().int().nonnegative()
+      }).optional(),
+      screenshot: looseObject({
+        mimeType: literal("image/png"),
+        width: number2().int().positive(),
+        height: number2().int().positive(),
+        bounds: jsonObject,
+        shapeCount: number2().int().positive(),
+        data: string2().optional()
+      }).optional(),
       preview: tldrawLatestPreview
     }),
     tldraw_exec: looseObject({
@@ -12783,7 +12841,8 @@ var OUTPUT_SHAPERS = {
   ]),
   create_topic: (result) => defined([
     ["topicId", result.id],
-    ["url", result.url]
+    ["url", result.url],
+    ["lifecycle", result.lifecycle]
   ]),
   create_thread: (result) => defined([
     ["threadId", result.id],
@@ -13016,6 +13075,9 @@ var OUTPUT_SHAPERS = {
     ["documentClock", result.documentClock],
     ["documentDigest", result.documentDigest],
     ["scene", result.scene],
+    ["presence", result.presence],
+    ["comments", result.comments],
+    ["screenshot", result.screenshot],
     ["preview", compactTldrawPreview(result.preview)]
   ]),
   computer_write: (result) => defined([
@@ -13294,12 +13356,37 @@ var shapeId = TLDRAW_SHAPE_ID_SCHEMA.describe("stable tldraw shape id, shape:…
 var shapeType = _enum(["geo", "text", "note", "frame", "arrow", "line", "draw", "group"]).describe("built-in tldraw shape type; use code mode for custom or asset-backed shapes");
 var finite = number2().finite();
 var jsonRecord = record(string2(), unknown());
+var diagramKey = string2().min(1).max(80).describe("caller-meaningful node key; returned as the alias for its generated tldraw shape id");
+var pageIdFilter = string2().min(1).max(200).describe("optional page id to search");
+var textRef = object({
+  text: string2().min(1).max(500),
+  match: _enum(["exact", "contains"]).optional().describe("exact (default, case/whitespace-insensitive) or contains"),
+  type: string2().min(1).max(64).optional().describe("optional shape type filter"),
+  pageId: pageIdFilter.optional()
+}).strict().describe("the one existing shape whose text matches");
+var descriptionRef = object({ description: string2().min(1).max(200), pageId: pageIdFilter.optional() }).strict().describe(`the one existing shape a description like 'the blue box labelled "API" in the top right' names (quoted label, kind, colour, region are strict filters)`);
+var selectedRef = object({ selected: literal(true) }).strict().describe("your one currently selected shape in an open board tab");
+var createdRef = object({
+  created: union([literal("last"), number2().int().min(0).max(TLDRAW_EXEC_MAX_OPERATIONS)])
+}).strict().describe('a shape created earlier in this batch: "last" or its 0-based create index');
+var keyRef = object({ key: diagramKey }).strict().describe("a diagram node created earlier in this batch, by its key");
+var TLDRAW_SHAPE_REF_SCHEMA = union([shapeId, textRef, descriptionRef, selectedRef, createdRef, keyRef]).describe("shape id, or { text } | { description } | { selected: true } | { created } | { key }; resolved before any edit, ambiguity refuses");
+var shapeRef = TLDRAW_SHAPE_REF_SCHEMA;
+var selectedAllRef = object({ selected: literal("all") }).strict().describe("every currently selected shape in your open board tab");
+var shapeRefs = array(union([shapeId, textRef, descriptionRef, selectedRef, createdRef, keyRef, selectedAllRef])).min(1).max(TLDRAW_EXEC_MAX_OPERATIONS);
+var place = object({
+  relativeTo: shapeRef.describe("the existing or earlier-created shape to place beside"),
+  side: _enum(["right", "left", "above", "below"]),
+  gap: finite.min(0).max(1e4).optional().describe("edge-to-edge gap; defaults to 40"),
+  align: _enum(["start", "center", "end"]).optional().describe("cross-axis alignment with the target; defaults to center")
+}).strict().describe("place the new shape beside another instead of giving x/y");
 var create = object({
   op: literal("create"),
   id: shapeId,
   type: shapeType,
-  x: finite,
-  y: finite,
+  x: finite.optional().describe("page x; omit only when place is given"),
+  y: finite.optional().describe("page y; omit only when place is given"),
+  place: place.optional(),
   parentId: string2().min(1).max(200).optional(),
   rotation: finite.optional(),
   opacity: finite.min(0).max(1).optional(),
@@ -13309,8 +13396,8 @@ var create = object({
 }).strict();
 var update = object({
   op: literal("update"),
-  id: shapeId,
-  type: shapeType,
+  id: shapeRef,
+  type: shapeType.optional().describe("optional; read from the resolved shape when omitted"),
   x: finite.optional(),
   y: finite.optional(),
   parentId: string2().min(1).max(200).optional(),
@@ -13320,20 +13407,18 @@ var update = object({
   props: jsonRecord.optional().describe("partial shape properties"),
   meta: jsonRecord.optional()
 }).strict();
-var shapeIds = array(shapeId).min(1).max(TLDRAW_EXEC_MAX_OPERATIONS);
-var diagramKey = string2().min(1).max(80).describe("caller-meaningful node key; returned as the alias for its generated tldraw shape id");
 var diagramLabel = string2().min(1).max(160);
 var stack = object({
   op: literal("stack"),
-  ids: shapeIds.min(2).describe("native shapes in the exact stack order; first id is the anchor"),
+  ids: shapeRefs.describe("shapes in the exact stack order; the first is the anchor (at least 2)"),
   axis: _enum(["horizontal", "vertical"]),
   gap: finite.min(0).describe("required edge-to-edge gap between adjacent shapes"),
   alignment: _enum(["start", "center", "end"]).optional().describe("optional cross-axis alignment relative to the first shape")
 }).strict();
 var connect = object({
   op: literal("connect"),
-  sourceId: shapeId.describe("existing native shape to bind the arrow start to"),
-  targetId: shapeId.describe("existing native shape to bind the arrow end to")
+  sourceId: shapeRef.describe("existing native shape to bind the arrow start to"),
+  targetId: shapeRef.describe("existing native shape to bind the arrow end to")
 }).strict();
 var diagram = object({
   op: literal("diagram"),
@@ -13351,26 +13436,32 @@ var diagram = object({
 var TLDRAW_EXEC_OPERATION_SCHEMA = discriminatedUnion("op", [
   create,
   update,
-  object({ op: literal("delete"), ids: shapeIds }).strict(),
+  object({ op: literal("delete"), ids: shapeRefs }).strict(),
   object({
     op: literal("align"),
-    ids: shapeIds.min(2),
+    ids: shapeRefs.describe("at least 2 shapes"),
     alignment: _enum(["bottom", "center-horizontal", "center-vertical", "left", "right", "top"])
   }).strict(),
   object({
     op: literal("distribute"),
-    ids: shapeIds.min(3),
+    ids: shapeRefs.describe("at least 3 shapes"),
     axis: _enum(["horizontal", "vertical"])
   }).strict(),
   object({
     op: literal("group"),
-    ids: shapeIds.min(2),
+    ids: shapeRefs.describe("at least 2 shapes"),
     groupId: shapeId.optional()
   }).strict(),
   stack,
   connect,
   diagram
 ]);
+var MIN_REFERENCE_COUNT = {
+  align: 2,
+  distribute: 3,
+  group: 2,
+  stack: 2
+};
 var TLDRAW_EXEC_OPERATIONS_SCHEMA = array(TLDRAW_EXEC_OPERATION_SCHEMA).min(1).max(TLDRAW_EXEC_MAX_OPERATIONS).superRefine((operations, ctx) => {
   const createdIds = new Set;
   const diagramKeys = new Set;
@@ -13387,20 +13478,43 @@ var TLDRAW_EXEC_OPERATIONS_SCHEMA = array(TLDRAW_EXEC_OPERATION_SCHEMA).min(1).m
       }
       createdIds.add(operation.id);
     }
+    if (operation.op === "create") {
+      const hasPoint = operation.x !== undefined || operation.y !== undefined;
+      if (operation.place ? hasPoint : operation.x === undefined || operation.y === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: "create needs both x and y, or place instead of x/y",
+          path: [index, operation.place ? "place" : "x"]
+        });
+      }
+    }
     if ("ids" in operation) {
       const seen = new Set;
       operation.ids.forEach((id, idIndex) => {
-        if (seen.has(id)) {
+        const key = typeof id === "string" ? id : JSON.stringify(id);
+        if (seen.has(key)) {
           ctx.addIssue({
             code: "custom",
-            message: `duplicate shape id: ${id}`,
+            message: `duplicate shape reference: ${key}`,
             path: [index, "ids", idIndex]
           });
         }
-        seen.add(id);
+        seen.add(key);
       });
+      const minimum = MIN_REFERENCE_COUNT[operation.op] ?? 1;
+      const expands = operation.ids.some((id) => typeof id === "object" && ("selected" in id) && id.selected === "all");
+      if (!expands && operation.ids.length < minimum) {
+        ctx.addIssue({
+          code: "too_small",
+          origin: "array",
+          minimum,
+          inclusive: true,
+          message: `${operation.op} needs at least ${minimum} shapes`,
+          path: [index, "ids"]
+        });
+      }
     }
-    if (operation.op === "connect" && operation.sourceId === operation.targetId) {
+    if (operation.op === "connect" && canonicalJson(operation.sourceId) === canonicalJson(operation.targetId)) {
       ctx.addIssue({
         code: "custom",
         message: "connect self-loops are not supported",
@@ -13464,6 +13578,16 @@ var TLDRAW_EXEC_OPERATIONS_SCHEMA = array(TLDRAW_EXEC_OPERATION_SCHEMA).min(1).m
     }
   });
 }).describe("preferred declarative edits, applied in order; mutually exclusive with code");
+function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => item === undefined ? "null" : canonicalJson(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
 // ../actions/src/index.ts
 var ARTIFACT_TYPE_DESCRIPTION = `semantic type (one of: ${ARTIFACT_TYPES.join(", ")})`;
 var ARBOR_FEEDBACK_INPUT_TYPES = [...ARBOR_FEEDBACK_TYPES, "friction"];
@@ -13511,7 +13635,7 @@ var ORIENTATION_SECTIONS = [
   },
   {
     brief: "1. Recall before re-deriving, but Arbor is memory, not truth: check live sources and post what you checked.",
-    full: `1. RECALL FIRST — but Arbor is MEMORY, NOT TRUTH. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. Phrase the query in PROBLEM-LANGUAGE (a natural-language question — "how do agents handle X"), not extracted keywords; it ranks better. Empty recall is itself worth noting. If you already know a place's name, \`tree\` with \`query\` returns that lookup only (example: \`360training / Delivery & Reviews\` is Space then Topic); \`tree\` without query maps structure you don't know — don't paginate it looking for a name. In a large Space, don't search the whole org by habit: scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. External tree reads page four roots; follow \`nextCursor\`, use \`all=true\` only for deliberate complete enumeration, and scope \`depth=threads\` to one Space or Topic. On that map, \`activeThreadCount\` is the current working set (active/stuck/needs-review/standing), while \`status\` is the Topic attention rollup: \`stuck\` means any stuck Thread; \`attention\` means needs-review or an open request; \`healthy\` means neither. A contribution records what was true when it was WRITTEN, so before you assert the CURRENT state of anything outside Arbor — a PR, a build, a deploy, a config — check the live source; another contribution is not evidence of the present, and neither is a local copy of something whose home is elsewhere. And when you DO check, post the RECEIPT with the claim (AD-209): attach the actual output/screenshot (an attached file becomes a durable artifact carrying who-captured-it and when, citable as #art_… forever) or name exactly what you checked and when ("CI run #841, green, checked just now") — a "verified" with no receipt is a claim the next reader must take on faith or re-derive. When a receipted claim has AGED and matters again, don't re-trust it and don't silently re-argue it: \`request\` a re-check ("re-run this check"), and whoever runs it answers through the request with fresh evidence. WHY: a room where everyone re-derives is just a chat log — but a room that mistakes its own memory for the world confidently reports blockers that no longer exist, and this week's failures were exactly that: stale claims re-asserted as current because nothing distinguished a receipted observation from confident prose. And orient to the ROOM the way you orient to the record: \`tree\` is the map AND the way in — it carries each room's \`lanesForYou\`, the room's standing ways to help (\`contributionLanes\`) that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full list of ways to help live. A way to help is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.`
+    full: `1. RECALL FIRST — but Arbor is MEMORY, NOT TRUTH. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. Phrase the query in PROBLEM-LANGUAGE (a natural-language question — "how do agents handle X"), not extracted keywords; it ranks better. Empty recall is itself worth noting. If you already know a place's name, \`tree\` with \`query\` returns that lookup only (example: \`360training / Delivery & Reviews\` is Space then Topic); \`tree\` without query maps structure you don't know — don't paginate it looking for a name. In a large Space, don't search the whole org by habit: scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. External tree reads page four roots; follow \`nextCursor\`, use \`all=true\` only for deliberate complete enumeration, and scope \`depth=threads\` to one Space or Topic. On that map, \`activeThreadCount\` is the current working set (active/stuck/needs-review/standing), while \`lifecycle\` is the Topic's deliberate status (planned, open, on-hold, closed), set by its owner or a Space admin and never derived from its Threads — a Closed Topic still takes new Threads. A contribution records what was true when it was WRITTEN, so before you assert the CURRENT state of anything outside Arbor — a PR, a build, a deploy, a config — check the live source; another contribution is not evidence of the present, and neither is a local copy of something whose home is elsewhere. And when you DO check, post the RECEIPT with the claim (AD-209): attach the actual output/screenshot (an attached file becomes a durable artifact carrying who-captured-it and when, citable as #art_… forever) or name exactly what you checked and when ("CI run #841, green, checked just now") — a "verified" with no receipt is a claim the next reader must take on faith or re-derive. When a receipted claim has AGED and matters again, don't re-trust it and don't silently re-argue it: \`request\` a re-check ("re-run this check"), and whoever runs it answers through the request with fresh evidence. WHY: a room where everyone re-derives is just a chat log — but a room that mistakes its own memory for the world confidently reports blockers that no longer exist, and this week's failures were exactly that: stale claims re-asserted as current because nothing distinguished a receipted observation from confident prose. And orient to the ROOM the way you orient to the record: \`tree\` is the map AND the way in — it carries each room's \`lanesForYou\`, the room's standing ways to help (\`contributionLanes\`) that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full list of ways to help live. A way to help is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.`
   },
   {
     brief: "2. Contribute one additive, typed point a newcomer can follow; stamp instead of restating.",
@@ -14106,7 +14230,14 @@ var ACTION_DEFINITIONS = [
         id: string2(),
         label: string2()
       })).optional().describe("inline @-mentions in the body; person mentions notify"),
-      links: array(object({ rel: _enum(CONTRIBUTION_ADD_LINK_RELS), targetId: string2() })).optional().describe("internal typed links: { rel, targetId } (same-space) — a DELIBERATE edge: inReplyTo/contests nests your contribution under the target (AD-196); body refs never do. External refs go IN THE BODY as URLs.")
+      links: array(object({ rel: _enum(CONTRIBUTION_ADD_LINK_RELS), targetId: string2() })).optional().describe("internal typed links: { rel, targetId } (same-space) — a DELIBERATE edge: inReplyTo/contests nests your contribution under the target (AD-196); body refs never do. External refs go IN THE BODY as URLs."),
+      anchor: object({
+        artifactId: string2().describe("a tldraw board whose source Thread is this Thread"),
+        shapeId: TLDRAW_SHAPE_ID_SCHEMA.optional(),
+        pageId: string2().min(1).max(200).optional(),
+        x: number2().finite().optional(),
+        y: number2().finite().optional()
+      }).strict().optional().describe("pin this contribution to a board as a comment: shapeId, or pageId + x/y page point; reply to one with links inReplyTo")
     },
     surfaces: ["mcp", "cli"],
     toolset: "loop",
@@ -14166,7 +14297,8 @@ var ACTION_DEFINITIONS = [
       title: string2().min(1).describe("the topic's name — an area of work, not a question"),
       purpose: string2().optional().describe("what this Topic accomplishes and what belongs here, leading with its primary role — Direction, Delivery, Operations, Intake, Coordination, or Learning; name an external or split source of truth or a handoff boundary only when it materially matters"),
       workflow: string2().optional().describe("a workflow id from `space_get.workflows` (pick by summary) — a built-in such as `queue` or a catalog `wfl_…`; must already be attached to this Space"),
-      visibility: _enum(["open", "private"]).optional().describe("`open` (default): every Space member sees it. `private`: only its roster plus the Space's admins and the org's owner/admins — creating one takes Space admin; you start on the roster")
+      visibility: _enum(["open", "private"]).optional().describe("`open` (default): every Space member sees it. `private`: only its roster plus the Space's admins and the org's owner/admins — creating one takes Space admin; you start on the roster"),
+      lifecycle: _enum(INITIAL_TOPIC_LIFECYCLES).optional().describe("the Topic's starting status: `open` (default) or `planned` (not started yet); change it later with `topic_update --lifecycle`")
     },
     surfaces: ["mcp", "cli"],
     toolset: "structure",
@@ -14174,14 +14306,15 @@ var ACTION_DEFINITIONS = [
   },
   {
     name: "topic_update",
-    title: "Edit a topic's title or purpose",
-    description: "Edit a Topic's title, purpose, or `--workflow` (pick from `space_get.workflows` by summary; blank inherits the Space default), patching only supplied fields, or archive it reversibly (`--archived true`, admin-only; `false` restores). Norms belong in topic guidance and ways to help, not here.",
+    title: "Edit a topic's title, purpose, or status",
+    description: "Edit a Topic's title, purpose, or `--workflow` (pick from `space_get.workflows` by summary; blank inherits the Space default), patching only supplied fields, or set its deliberate status with `--lifecycle` (`archived`: admin-only). Norms belong in topic guidance and ways to help, not here.",
     inputSchema: {
       topicId: string2().describe("the topic to edit, top_…"),
       title: string2().min(1).optional().describe("a new title — an area of work, not a question"),
       purpose: string2().optional().describe("a new purpose — what this Topic accomplishes and what belongs here, leading with its primary role (Direction, Delivery, Operations, Intake, Coordination, or Learning); name an external or split source of truth or a handoff boundary only when it materially matters"),
       workflow: string2().nullable().optional().describe("a workflow id from `space_get.workflows` (pick by summary) — a built-in such as `queue` or a catalog `wfl_…`; must be attached to the Space; blank or null inherits the Space default"),
-      archived: boolean2().optional().describe("true archives the Topic: it and everything in it leave the Space read, tree, thread lists and default recall and become read-only, each Thread keeping its status; false restores it. Org owner/admin or Space admin only, as the only change; refused while a Run in it is active"),
+      lifecycle: _enum(TOPIC_LIFECYCLES).optional().describe("the Topic's status, as the only change: `planned` (not started), `open` (the default), `on-hold` (paused), `closed` (finished; still visible and still takes new Threads) — the Topic owner or a Space admin; `archived` (hidden and read-only until restored, refused while a Run in it is active) — org owner/admin or Space admin only, and leaving it likewise. Never changes a Thread's status"),
+      archived: boolean2().optional().describe("same as `--lifecycle archived` (true) or restoring an archived Topic to `open` (false): it and everything in it leave the Space read, tree, thread lists and default recall and become read-only, each Thread keeping its status. Org owner/admin or Space admin only, as the only change; refused while a Run in it is active"),
       visibility: _enum(["open", "private"]).optional().describe("Space admin only: `private` limits the Topic (its threads, contributions, artifacts) to its roster plus Space/org admins; `open` shows it to every Space member again")
     },
     surfaces: ["mcp", "cli"],
@@ -16292,7 +16425,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "tldraw_observe",
     title: "Observe a tldraw board",
-    description: `Read bounded scene/clock/digest/lint, scoped by shape ids or region; preview defaults to metadata, ensure reuses/renders latest PNG (renderInProgress: retry shortly); lint is advisory. MCP is links-only for viewing/downloading (model pixels vary by client); signedRead is 5-min/single-Attachment, never for posts; use permanent markdown; guide: ${AGENT_GUIDE_URLS.tldraw}.`,
+    description: `Read bounded scene/clock/digest/lint with labelled clusters, your own open tab's presence, and anchored comments, scoped by ids, region, or clusterIds; screenshot renders just the scope inline; preview ensure reuses/renders the board PNG (renderInProgress: retry shortly). Preview is links-only; signedRead is 5-min, never for posts; guide: ${AGENT_GUIDE_URLS.tldraw}.`,
     inputSchema: {
       artifactId: string2().describe("the tldraw Artifact, art_…"),
       pageId: string2().min(1).max(200).optional().describe("optional page to observe"),
@@ -16303,6 +16436,13 @@ var ACTION_DEFINITIONS = [
         width: number2().finite().positive(),
         height: number2().finite().positive()
       }).optional().describe("optional page-coordinate rectangle; returns shapes whose page bounds intersect it, and combines with ids by intersection"),
+      clusterIds: array(string2().regex(/^cluster:[0-9a-z]{1,13}(?:-\d{1,4})?$/)).min(1).max(50).refine((values) => new Set(values).size === values.length, "cluster ids must be unique").optional().describe("drill into these clusters from a prior observe (ids change when their shapes do); intersects with ids/region"),
+      clusterCursor: string2().max(32).optional().describe("continue the cluster listing from a prior observe's scene.nextClusterCursor"),
+      view: _enum(["full", "clusters"]).optional().describe("full (default) returns shapes; clusters returns only the cluster overview"),
+      screenshot: object({
+        maxWidth: number2().int().min(64).max(1536).optional(),
+        maxHeight: number2().int().min(64).max(1536).optional()
+      }).strict().optional().describe("render only the observed scope (clusterIds/ids/region, else the page) as a PNG fitting maxWidth×maxHeight (default 768); returned as image content"),
       viewportWidth: number2().int().min(320).max(1920).optional(),
       viewportHeight: number2().int().min(240).max(1080).optional(),
       preview: _enum(["metadata", "ensure"]).optional().describe("preview behavior; defaults to metadata, while ensure explicitly refreshes only when stale/missing")
@@ -16314,7 +16454,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "tldraw_exec",
     title: "Run a one-shot tldraw program",
-    description: `Modify the current live tldraw board with preferred declarative operations or bounded JavaScript, including graph-scoped diagram layout, ordered exact-gap stack composition, and safe native bound connect without caller-supplied connector geometry, then return a durable execution receipt; use IDs from a fresh observe, reacquire this current schema after compaction, and never replay an unknown result. First use: read the tldraw guide at ${AGENT_GUIDE_URLS.tldraw}.`,
+    description: `Modify the live tldraw board with preferred declarative operations or bounded JavaScript (diagram layout, exact-gap stack, native bound connect, create place); operations take shape ids or { text | description | selected | created | key } references resolved before any edit, and ambiguity refuses the batch. Returns a durable receipt; reacquire this schema after compaction and never replay an unknown result; first use: read the tldraw guide at ${AGENT_GUIDE_URLS.tldraw}.`,
     inputSchema: {
       artifactId: string2().describe("the tldraw Artifact, art_…"),
       code: string2().min(1).max(1e5).optional().describe("advanced script source; mutually exclusive with operations"),
@@ -16841,7 +16981,7 @@ var ACTIONS = ACTION_DEFINITIONS.map((action) => {
 });
 
 // ../actions/src/retention-entry.ts
-var ARBOR_VERSION = "0.24.34";
+var ARBOR_VERSION = "0.24.36";
 var historyPolicySchema = _enum(["full", "checkpoint"]).optional().describe("text Artifacts: future history retention policy; full retains every source snapshot, checkpoint keeps metadata for every revision and source only when explicitly retained");
 var retainSourceSchema = boolean2().optional().describe("edit: in checkpoint mode, retain this newly minted content revision's source");
 var checkpointSchema = boolean2().optional().describe("edit: retain the exact current version source without incrementing content version");
@@ -17249,7 +17389,7 @@ function dispositionFilename(value) {
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.24.34",
+  version: "0.24.36",
   description: "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   keywords: [
     "agents",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.24.34",
+  "version": "0.24.36",
   "description": "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   "keywords": [
     "agents",