@lambdacurry/arbor 0.13.5 → 0.13.6

package/dist/arbor.js

@@ -16844,6 +16844,13 @@ var MCP_OUTPUT_SCHEMAS = {
     all: exports_external.array(initiative3).optional(),
     ok: exports_external.boolean().optional()
   }),
+  goal_get: exports_external.looseObject({ initiative: initiative3 }),
+  goal_list: exports_external.looseObject({
+    initiatives: exports_external.array(initiative3).optional(),
+    linked: exports_external.array(initiative3).optional(),
+    all: exports_external.array(initiative3).optional()
+  }),
+  goal_delete: exports_external.looseObject({ ok: exports_external.boolean() }),
   membership: exports_external.looseObject({
     spaceId: id.optional(),
     profileId: id.optional(),
@@ -16859,20 +16866,32 @@ var MCP_OUTPUT_SCHEMAS = {
     nextCursor: exports_external.string().optional(),
     ok: exports_external.boolean().optional()
   }),
-  notification: exports_external.looseObject({
+  space_leave: exports_external.looseObject({ spaceId: id, left: exports_external.boolean() }),
+  space_list_open: paged("spaces", space3),
+  space_invitation_list: paged("invitations", jsonObject),
+  notification_list: exports_external.looseObject({
     items: exports_external.array(jsonObject).optional(),
     total: exports_external.number().optional(),
     unseenCount: exports_external.number().optional(),
     lastSeenAt: timestamp.nullable().optional(),
-    notificationId: id.optional(),
-    read: exports_external.boolean().optional(),
-    markedCount: exports_external.number().optional(),
     nextCursor: exports_external.string().optional()
   }),
+  notification_read: exports_external.looseObject({
+    notificationId: id.optional(),
+    read: exports_external.boolean().optional()
+  }),
+  notification_read_all: exports_external.looseObject({
+    markedCount: exports_external.number().optional()
+  }),
   watch: exports_external.looseObject({
     targetType: exports_external.string().optional(),
     targetId: id.optional(),
-    watching: exports_external.boolean().optional(),
+    watching: exports_external.boolean().optional()
+  }),
+  watch_get: exports_external.looseObject({
+    watching: exports_external.boolean()
+  }),
+  watch_list: exports_external.looseObject({
     watches: exports_external.array(jsonObject).optional()
   }),
   curation: exports_external.looseObject({
@@ -16900,23 +16919,59 @@ var MCP_OUTPUT_SCHEMAS = {
     versions: exports_external.array(jsonObject).optional(),
     appBundles: exports_external.array(jsonObject).optional()
   }),
-  apps: exports_external.looseObject({
-    result: exports_external.array(app2).optional(),
-    spaceId: id.optional(),
-    title: exports_external.string().optional(),
-    slug: exports_external.string().optional(),
-    access: exports_external.string().optional(),
-    stateMode: exports_external.string().optional(),
-    app: app2.optional(),
-    deployment: deployment.optional(),
-    deployments: exports_external.array(jsonObject).optional(),
-    bundle: jsonObject.optional(),
-    reset: jsonObject.optional(),
-    activated: exports_external.boolean().optional(),
+  artifact_get: exports_external.looseObject({
+    id,
+    title: exports_external.string(),
+    kind: exports_external.string(),
+    status: exports_external.string(),
+    content: jsonObject,
+    version: exports_external.number().optional(),
+    versions: exports_external.array(jsonObject).optional(),
+    appBundles: exports_external.array(jsonObject),
+    watching: exports_external.boolean(),
+    url: exports_external.string()
+  }),
+  artifact_transition: exports_external.looseObject({
+    artifactId: id,
+    status: exports_external.string(),
+    retrievalTier: exports_external.string()
+  }),
+  artifact_delete: exports_external.looseObject({
+    artifactId: id,
+    status: exports_external.literal("deleted"),
+    retrievalTier: exports_external.string()
+  }),
+  app_list: exports_external.object({ result: exports_external.array(app2) }),
+  app_get: exports_external.looseObject({
+    app: app2,
+    deployments: exports_external.array(jsonObject),
+    resets: exports_external.array(jsonObject),
+    events: exports_external.array(jsonObject),
+    url: exports_external.string()
+  }),
+  app_deployment_get: exports_external.looseObject({ deployment, bundle: jsonObject }),
+  app_create: app2,
+  app_deploy: exports_external.looseObject({
+    deployment,
+    activated: exports_external.boolean(),
+    url: exports_external.string(),
+    replayed: exports_external.boolean().optional()
+  }),
+  app_activate: exports_external.looseObject({
+    app: app2,
+    deployment,
     replayed: exports_external.boolean().optional(),
-    url: exports_external.string().optional(),
-    id: id.optional()
+    url: exports_external.string()
+  }),
+  app_rollback: exports_external.looseObject({
+    app: app2,
+    deployment,
+    replayed: exports_external.boolean().optional(),
+    url: exports_external.string()
   }),
+  app_set_access: app2,
+  app_reset_state: exports_external.looseObject({ reset: jsonObject, replayed: exports_external.boolean() }),
+  app_archive: app2,
   charter: exports_external.looseObject({
     ok: exports_external.boolean().optional(),
     space: space3.optional(),
@@ -16990,9 +17045,19 @@ var MCP_OUTPUT_SCHEMAS = {
     head: exports_external.string().optional(),
     refs: exports_external.array(exports_external.string()).optional()
   }),
-  computer_sync: exports_external.looseObject({
+  computer_fetch: exports_external.looseObject({
     ok: exports_external.literal(true),
-    operation: exports_external.enum(["fetch", "pull", "push"]),
+    operation: exports_external.literal("fetch"),
+    repository: exports_external.string(),
+    dir: exports_external.string(),
+    branch: exports_external.string().optional(),
+    head: exports_external.string().optional(),
+    fetchHead: exports_external.string().optional(),
+    refs: exports_external.array(exports_external.string()).optional()
+  }),
+  computer_pull: exports_external.looseObject({
+    ok: exports_external.literal(true),
+    operation: exports_external.literal("pull"),
     repository: exports_external.string(),
     dir: exports_external.string(),
     branch: exports_external.string().optional(),
@@ -17002,6 +17067,17 @@ var MCP_OUTPUT_SCHEMAS = {
     fetchHead: exports_external.string().optional(),
     refs: exports_external.array(exports_external.string()).optional()
   }),
+  computer_push: exports_external.looseObject({
+    ok: exports_external.literal(true),
+    operation: exports_external.literal("push"),
+    repository: exports_external.string(),
+    dir: exports_external.string(),
+    branch: exports_external.string().optional(),
+    head: exports_external.string().optional(),
+    before: exports_external.string().optional(),
+    after: exports_external.string().optional(),
+    refs: exports_external.array(exports_external.string()).optional()
+  }),
   computer_checkpoint: checkpoint,
   computer_publish_preview: exports_external.looseObject({
     previewId: id,
@@ -17031,6 +17107,141 @@ function outputSchemaFor(actionName) {
   return MCP_OUTPUT_SCHEMAS[actionName];
 }
 
+// ../actions/src/tool-annotations.ts
+var readOnly = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var additive = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var destructive = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var idempotent = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var destructiveIdempotent = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var openWorld = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var destructiveOpenWorld = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var idempotentOpenWorld = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var MCP_TOOL_ANNOTATIONS = {
+  recall: readOnly,
+  contribute: additive,
+  edit: additive,
+  stamp: additive,
+  react: idempotent,
+  create_topic: additive,
+  topic_update: additive,
+  create_thread: additive,
+  set_organization_computer: additive,
+  set_space_computer: additive,
+  set_topic_computer: additive,
+  set_thread_computer: additive,
+  attach_computer: additive,
+  get_computer: readOnly,
+  publish_topic_computer: additive,
+  checkpoint_computer: additive,
+  transition_thread: additive,
+  request: additive,
+  respond: additive,
+  mark_as_response: idempotent,
+  cancel_request: destructive,
+  inbox: readOnly,
+  dismiss: destructive,
+  whoami: readOnly,
+  introduce: additive,
+  thread_get: readOnly,
+  tree: readOnly,
+  members: readOnly,
+  space_create: additive,
+  space_update: additive,
+  space_get: readOnly,
+  topic_get: readOnly,
+  goal_get: readOnly,
+  goal_list: readOnly,
+  goal: additive,
+  goal_delete: destructive,
+  membership: additive,
+  space_leave: destructive,
+  space_list_open: readOnly,
+  space_invitation_list: readOnly,
+  notification_list: readOnly,
+  notification_read: idempotent,
+  notification_read_all: idempotent,
+  watch: idempotent,
+  watch_get: readOnly,
+  watch_list: readOnly,
+  curation: additive,
+  artifact: additive,
+  artifact_get: readOnly,
+  artifact_transition: additive,
+  artifact_delete: destructive,
+  app_get: readOnly,
+  app_list: readOnly,
+  app_deployment_get: readOnly,
+  app_create: additive,
+  app_deploy: idempotent,
+  app_activate: additive,
+  app_rollback: additive,
+  app_set_access: additive,
+  app_reset_state: destructiveIdempotent,
+  app_archive: additive,
+  charter: destructive,
+  computer_open: additive,
+  computer_exec: destructiveOpenWorld,
+  computer_status: readOnly,
+  computer_verify: openWorld,
+  computer_read: readOnly,
+  computer_export: idempotent,
+  computer_write: destructive,
+  computer_clone: idempotentOpenWorld,
+  computer_fetch: idempotentOpenWorld,
+  computer_pull: destructiveOpenWorld,
+  computer_push: destructiveOpenWorld,
+  computer_checkpoint: additive,
+  computer_publish_preview: idempotent,
+  computer_publish_app_bundle: idempotent,
+  computer_stop: additive
+};
+function mcpAnnotationsFor(name) {
+  const annotations = MCP_TOOL_ANNOTATIONS[name];
+  if (!annotations)
+    throw new Error(`${name}: MCP action is missing behavior annotations`);
+  return annotations;
+}
+
 // ../actions/src/index.ts
 var CONTRIBUTION_ADD_LINK_RELS = [
   "cites",
@@ -17050,7 +17261,7 @@ var ORIENTATION = `Arbor is your team's deliberation room and shared memory —
 6. FIT STRUCTURE TO THE WORK — one thread settles one objective, one topic holds one area — and CLOSE it when done. Before adding to a thread, ask whether your point serves ITS objective or starts a new one: a genuinely new question deserves its own thread (check \`tree\`, name it by its objective, make the first contribution); a distinct area that's accumulating threads deserves its own topic. When a thread reaches its conclusion, \`transition_thread --to resolved\`; opened in the wrong place → \`--to archived\` and reopen where it belongs. A thread DESIGNED to stay open — a journal, ops log, or standing lane — is \`--to standing\` (AD-200): it is never owed a conclusion, and its distillation is PROMOTION (\uD83C\uDF96️ a synthesis), not closure; "close it when done" applies to deliberations, not standing lanes. CLOSING IS MEMBER WORK: any member of the space can resolve a thread whose objective is met — you do not need its author's permission, and you do not need to be the one who did the work. Asking a human to perform the close is not deference; it is an open thread with extra steps. If the objective is met, close it and say why. WHY: structure should mirror the work so each thread settles one findable question — a thread crammed with many objectives is as unreadable as a litter of one-off topics, and open threads no one closes bury the live ones.
 7. ACT, THEN REPORT — escalate by exception (AD-197). Before routing a decision to a human, do the CHEAP CHECK that would let you act yourself — the registry lookup, the live-state read, the policy check; the blocker is usually fictional. Then: recoverable + conclusive evidence → act and say why. Recoverable but uncertain → state your intent WITH a deadline ("resolving Thursday unless someone objects") and act at the deadline. Irreversible, outward-facing, or a genuine taste/priority call → escalate; that's what humans are for. Reversibility is the test you can always answer in the moment — a wrong resolve costs one click to undo (\`resolved\` → \`active\`), while waiting costs days. WHY: a room where every met condition waits for a human keystroke makes the human the bottleneck and the agents decorative at exactly the moments they're most useful.
 
-8. DURABLE OUTPUT IS AN ARTIFACT, NOT A LONG CONTRIBUTION (AD-201). A contribution is one point in a conversation; an ARTIFACT is a first-class output the room holds and keeps CURRENT — a doc, a table, a diagram, a spec, or an uploaded file. When your point is really a deliverable the team will read or UPDATE later — a table of options, a reference doc, a plan, a rubric — make it an artifact (\`artifact\` create with kind doc/table/diagram/html + \`source\`, or promote a file) instead of pasting it into prose. Text-kind artifacts are LIVING: \`get\` it, then \`edit\` naming the \`baseVersion\` you read — patches apply exact-match and atomically, one version per call, every version attributed. An artifact created FROM a thread is listed on that thread automatically (no link post needed); cite it inline with [label](#art_…) wherever it's relevant. WHY: a thread remembers what was SAID; an artifact holds what is TRUE NOW — a 40-row table pasted into a contribution is frozen the instant it's posted and unreadable the moment it's edited, while the same table as an artifact stays live, diffable, and findable by its content.
+8. DURABLE OUTPUT IS AN ARTIFACT, NOT A LONG CONTRIBUTION (AD-201). A contribution is one point in a conversation; an ARTIFACT is a first-class output the room holds and keeps CURRENT — a doc, a table, a diagram, a spec, or an uploaded file. When your point is really a deliverable the team will read or UPDATE later — a table of options, a reference doc, a plan, a rubric — make it an artifact (\`artifact\` verb=create with kind doc/table/diagram/html + \`source\`, or promote a file) instead of pasting it into prose. Text-kind artifacts are LIVING: \`artifact_get\` it, then \`artifact\` verb=edit naming the \`baseVersion\` you read — patches apply exact-match and atomically, one version per call, every version attributed. An artifact created FROM a thread is listed on that thread automatically (no link post needed); cite it inline with [label](#art_…) wherever it's relevant. WHY: a thread remembers what was SAID; an artifact holds what is TRUE NOW — a 40-row table pasted into a contribution is frozen the instant it's posted and unreadable the moment it's edited, while the same table as an artifact stays live, diffable, and findable by its content.
 
 Run \`arbor help\` (or read the MCP tool list) for the exact command/flags — those stay generated from the live action surface, so they're always current.`;
 var PROSE_LISTS = exports_external.registry();
@@ -17461,10 +17672,52 @@ var ACTION_DEFINITIONS = [
       githubToken: exports_external.string().min(1).describe("short-lived GitHub token supplied by the caller"),
       githubUsername: exports_external.string().optional().describe("GitHub username; defaults to x-access-token")
     },
-    surfaces: ["computer-mcp", "computer-cli"],
+    surfaces: ["computer-cli"],
     toolset: "loop",
     run: forward("computer_runtime.sync")
   },
+  {
+    name: "computer_fetch",
+    title: "Fetch an allowed repository",
+    description: "Fetch remote refs for a cloned recipe repository without changing its checked-out branch or any remote ref. The collaborator's GitHub token is spent only on this call and is neither stored nor returned.",
+    inputSchema: {
+      computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
+      repository: exports_external.string().describe("allowed owner/repository slug already cloned"),
+      githubToken: exports_external.string().min(1).describe("short-lived GitHub token supplied by the caller"),
+      githubUsername: exports_external.string().optional().describe("GitHub username; defaults to x-access-token")
+    },
+    surfaces: ["computer-mcp"],
+    toolset: "loop",
+    run: (ex, input) => ex.call("computer_runtime.sync", { ...input, operation: "fetch" })
+  },
+  {
+    name: "computer_pull",
+    title: "Fast-forward an allowed repository",
+    description: "Fetch and fast-forward the checked-out branch of a cloned recipe repository; divergent history is rejected. The collaborator's GitHub token is spent only on this call and is neither stored nor returned.",
+    inputSchema: {
+      computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
+      repository: exports_external.string().describe("allowed owner/repository slug already cloned"),
+      githubToken: exports_external.string().min(1).describe("short-lived GitHub token supplied by the caller"),
+      githubUsername: exports_external.string().optional().describe("GitHub username; defaults to x-access-token")
+    },
+    surfaces: ["computer-mcp"],
+    toolset: "loop",
+    run: (ex, input) => ex.call("computer_runtime.sync", { ...input, operation: "pull" })
+  },
+  {
+    name: "computer_push",
+    title: "Push an allowed repository",
+    description: "Push the checked-out branch to its fixed allowlisted GitHub repository without force-pushing or deleting refs. The collaborator's GitHub token is spent only on this call and is neither stored nor returned.",
+    inputSchema: {
+      computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
+      repository: exports_external.string().describe("allowed owner/repository slug already cloned"),
+      githubToken: exports_external.string().min(1).describe("short-lived GitHub token supplied by the caller"),
+      githubUsername: exports_external.string().optional().describe("GitHub username; defaults to x-access-token")
+    },
+    surfaces: ["computer-mcp"],
+    toolset: "loop",
+    run: (ex, input) => ex.call("computer_runtime.sync", { ...input, operation: "push" })
+  },
   {
     name: "computer_checkpoint",
     title: "Checkpoint completed work",
@@ -17493,7 +17746,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_publish_app_bundle",
     title: "Publish an immutable AppBundle",
-    description: "After a Bun container build is green, freeze one Worker entry module plus optional static assets from this Thread computer into a content-addressed AppBundle sourced from an ArtifactVersion. Use the returned bundleId with apps verb=deploy (CLI: app_deploy); uploads complete and verify before Arbor publishes the bundle manifest, and retries require the same idempotencyKey.",
+    description: "After a Bun container build is green, freeze one Worker entry module plus optional static assets from this Thread computer into a content-addressed AppBundle sourced from an ArtifactVersion. Use the returned bundleId with app_deploy; uploads complete and verify before Arbor publishes the bundle manifest, and retries require the same idempotencyKey.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       artifactVersionId: exports_external.string().describe("the source ArtifactVersion, artv_…"),
@@ -17815,7 +18068,7 @@ var ACTION_DEFINITIONS = [
     inputSchema: {
       notificationId: exports_external.string().describe("the notification id, ntf_…")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "loop",
     run: forward("notification.markRead")
   },
@@ -17824,7 +18077,7 @@ var ACTION_DEFINITIONS = [
     title: "Mark all notifications read",
     description: "Mark every unread notification in your feed read in one call; returns how many were cleared. Reach for this to zero out your awareness feed after a catch-up.",
     inputSchema: {},
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "loop",
     run: forward("notification.markAllRead")
   },
@@ -18235,63 +18488,84 @@ var ACTION_DEFINITIONS = [
     toolset: "admin",
     run: forward("admin.getThread")
   },
+  {
+    name: "goal_get",
+    title: "Read one goal",
+    description: "Read one goal fully, including its purpose, lifecycle, attached Spaces, and related Threads visible to you. It cannot create, update, link, archive, or delete a goal.",
+    inputSchema: { id: exports_external.string().describe("the goal, ini_…") },
+    surfaces: ["mcp"],
+    toolset: "goals",
+    run: forward("initiative.get")
+  },
+  {
+    name: "goal_list",
+    title: "List goals",
+    description: "List the goals attached to one Space, or the linked and available goals for one Thread. It cannot create, update, link, archive, or delete a goal.",
+    inputSchema: {
+      spaceId: exports_external.string().optional().describe("a Space whose attached goals to list, spc_…"),
+      threadId: exports_external.string().optional().describe("a Thread whose linked and available goals to list, thr_…")
+    },
+    surfaces: ["mcp"],
+    toolset: "goals",
+    run: (ex, input) => {
+      if (typeof input.spaceId === "string")
+        return ex.call("initiative.listForSpace", { spaceId: input.spaceId });
+      if (typeof input.threadId === "string")
+        return ex.call("initiative.forThread", { threadId: input.threadId });
+      return Promise.reject(new Error("goal_list requires a spaceId (a Space's goals) or a threadId (a Thread's goals)"));
+    }
+  },
   {
     name: "goal",
-    title: "Work with goals",
-    description: "GOALS (initiatives) — the wide 'why' threads serve toward (AD-146/180). verb=get (id — one goal read fully, ANY status incl. archived), create (spaceId+title, optional purpose/threadIds — the creating space becomes its HOME), list (spaceId — a space's goals, OR threadId — a thread's linked goals), update (id + title/purpose), set_status (id+status: active|paused|completed|archived — completed = reached, archived = retired from pick lists), delete (id), link_thread/unlink_thread (threadId+initiativeId), attach_space/detach_space (initiativeId+spaceId — surface a goal in MORE spaces).",
+    title: "Manage goals",
+    description: "Create, update, change lifecycle, or change the Space/Thread links of a goal (initiative). Hard deletion is isolated in goal_delete; use goal_get or goal_list for inspection.",
     inputSchema: {
       verb: exports_external.enum([
         "create",
-        "list",
         "update",
         "set_status",
-        "delete",
         "link_thread",
         "unlink_thread",
         "attach_space",
         "detach_space"
       ]).describe("which goal move to make"),
-      spaceId: exports_external.string().optional().describe("create: HOME space · list: a space's goals · attach/detach_space: the target space, spc_…"),
+      spaceId: exports_external.string().optional().describe("create: HOME space · attach/detach_space: the target space, spc_…"),
       title: exports_external.string().optional().describe("create/update: the goal's name — an outcome, not a task"),
       purpose: exports_external.string().optional().describe("create/update: one or two lines on what reaching it means"),
       threadIds: exports_external.array(exports_external.string()).optional().describe("create: threads to link at birth"),
-      id: exports_external.string().optional().describe("get/update/set_status/delete: the goal, ini_…"),
+      id: exports_external.string().optional().describe("update/set_status: the goal, ini_…"),
       status: exports_external.enum(["active", "paused", "completed", "archived"]).optional().describe("set_status: the new lifecycle state"),
-      threadId: exports_external.string().optional().describe("list/link_thread/unlink_thread: the thread, thr_…"),
+      threadId: exports_external.string().optional().describe("link_thread/unlink_thread: the thread, thr_…"),
       initiativeId: exports_external.string().optional().describe("link/unlink/attach/detach: the goal, ini_…")
     },
     surfaces: ["mcp"],
     toolset: "goals",
-    run: (ex, input) => {
-      const { verb, spaceId, threadId } = input;
-      if (verb === "list") {
-        if (typeof spaceId === "string")
-          return ex.call("initiative.listForSpace", { spaceId });
-        if (typeof threadId === "string")
-          return ex.call("initiative.forThread", { threadId });
-        return Promise.reject(new Error("goal list requires a spaceId (a space's goals) or a threadId (a thread's goals)"));
-      }
-      return dispatch({
-        get: "initiative.get",
-        create: "initiative.create",
-        list: "initiative.forThread",
-        update: "initiative.update",
-        set_status: "initiative.setStatus",
-        delete: "initiative.delete",
-        link_thread: "initiative.linkThread",
-        unlink_thread: "initiative.unlinkThread",
-        attach_space: "initiative.attachSpace",
-        detach_space: "initiative.detachSpace"
-      })(ex, input);
-    }
+    run: dispatch({
+      create: "initiative.create",
+      update: "initiative.update",
+      set_status: "initiative.setStatus",
+      link_thread: "initiative.linkThread",
+      unlink_thread: "initiative.unlinkThread",
+      attach_space: "initiative.attachSpace",
+      detach_space: "initiative.detachSpace"
+    })
+  },
+  {
+    name: "goal_delete",
+    title: "Permanently delete a goal",
+    description: "Permanently delete a mistaken or duplicate goal and all of its Space/Thread links. This is irreversible; archive a goal through goal instead when its history should remain.",
+    inputSchema: { id: exports_external.string().describe("the goal to permanently delete, ini_…") },
+    surfaces: ["mcp"],
+    toolset: "goals",
+    run: forward("initiative.delete")
   },
   {
     name: "membership",
     title: "Space membership moves",
-    description: "Your space membership, in one tool. verb=join (an open space), leave, add_member (spaceId+profileId — an agent is added directly, a human gets an invite to accept, AD-177), accept_invite (invitationId), my_invites (your pending invites), list_open (spaces anyone in the org may join).",
+    description: "Join an open Space, add a member, or accept one invitation. Leaving is isolated in space_leave; read available Spaces with space_list_open and pending invitations with space_invitation_list.",
     inputSchema: {
-      verb: exports_external.enum(["join", "leave", "add_member", "accept_invite", "my_invites", "list_open"]).describe("which membership move to make"),
-      spaceId: exports_external.string().optional().describe("join/leave/add_member: the space, spc_…"),
+      verb: exports_external.enum(["join", "add_member", "accept_invite"]).describe("which membership move to make"),
+      spaceId: exports_external.string().optional().describe("join/add_member: the Space, spc_…"),
       profileId: exports_external.string().optional().describe("add_member: who to add, prof_…"),
       invitationId: exports_external.string().optional().describe("accept_invite: the invitation, sinv_…")
     },
@@ -18299,48 +18573,83 @@ var ACTION_DEFINITIONS = [
     toolset: "spaces",
     run: dispatch({
       join: "space.join",
-      leave: "space.leave",
       add_member: "space.addMember",
-      accept_invite: "space.acceptInvite",
-      my_invites: "space.invites",
-      list_open: "space.listOpen"
+      accept_invite: "space.acceptInvite"
     })
   },
   {
-    name: "notification",
-    title: "Your awareness feed",
-    description: "Awareness, never obligation (`inbox` is the only obligation surface). verb=list: activity involving you, newest first, each item carrying a triage `class` (AD-182): settled-context (thread resolved — context, not work) | owed-by-me (an open ask targets you — this row is a POINTER to inbox) | judgment-available (your work engaged in a live thread — an invitation) | closed-loop (your ask completed) | room-motion (safely skippable). verb=read (notificationId) clears one row; verb=read_all clears the feed.",
-    inputSchema: {
-      verb: exports_external.enum(["list", "read", "read_all"]).describe("list the feed, or clear one/all"),
-      notificationId: exports_external.string().optional().describe("read: the notification, ntf_…"),
-      ...PAGINATION_INPUT
-    },
+    name: "space_leave",
+    title: "Leave a Space",
+    description: "Leave one Space and give up your membership. Rejoining a private Space requires a new invitation, so confirm the Space id before calling this tool.",
+    inputSchema: { spaceId: exports_external.string().describe("the Space to leave, spc_…") },
+    surfaces: ["mcp"],
+    toolset: "spaces",
+    run: forward("space.leave")
+  },
+  {
+    name: "space_list_open",
+    title: "List open Spaces",
+    description: "List open Spaces in your organization and whether you already belong to each one. It cannot join, leave, invite, or otherwise change Space membership.",
+    inputSchema: { ...PAGINATION_INPUT },
+    surfaces: ["mcp"],
+    toolset: "spaces",
+    run: forward("space.listOpen")
+  },
+  {
+    name: "space_invitation_list",
+    title: "List my Space invitations",
+    description: "List the pending Space invitations addressed to you. It cannot accept an invitation or change any Space membership.",
+    inputSchema: { ...PAGINATION_INPUT },
+    surfaces: ["mcp"],
+    toolset: "spaces",
+    run: forward("space.invites")
+  },
+  {
+    name: "notification_list",
+    title: "List your notifications",
+    description: "List your awareness feed newest first, including unseen count and each item's triage class. It cannot mark notifications read or modify inbox obligations.",
+    inputSchema: { ...PAGINATION_INPUT },
     surfaces: ["mcp"],
     toolset: "loop",
-    run: dispatch({
-      list: "notification.list",
-      read: "notification.markRead",
-      read_all: "notification.markAllRead"
-    })
+    run: forward("notification.list")
   },
   {
     name: "watch",
-    title: "Watch for changes",
-    description: "CHOSEN attention (AD-202) — subscribe to a thread/artifact/topic and get a notification when it changes, even on work you didn't touch (participation already notifies you about threads you're in; watch is for the rest). verb=on: start watching (targetType thread|artifact|topic + targetId). verb=off: stop. verb=status: are you watching this one? verb=list: everything you watch. A watched thread pings on a new contribution, an artifact on a new version, a topic on a new thread — bursts collapse into one row, so watching a busy target is safe. Watching is PRIVATE (nobody sees you watch).",
+    title: "Change a watch",
+    description: "Start or stop your private watch on one Thread, Artifact, or Topic; repeated on/off calls are idempotent. Inspect watches with watch_get or watch_list.",
     inputSchema: {
-      verb: exports_external.enum(["on", "off", "status", "list"]).describe("start/stop/check watching, or list"),
-      targetType: exports_external.enum(["thread", "artifact", "topic"]).optional().describe("on/off/status: what to watch"),
-      targetId: exports_external.string().optional().describe("on/off/status: the id (thr_/art_/top_)")
+      verb: exports_external.enum(["on", "off"]).describe("start or stop watching"),
+      targetType: exports_external.enum(["thread", "artifact", "topic"]).describe("what to watch"),
+      targetId: exports_external.string().describe("the id (thr_/art_/top_)")
     },
     surfaces: ["mcp"],
     toolset: "loop",
     run: dispatch({
       on: "watch.toggle",
-      off: "watch.toggle",
-      status: "watch.get",
-      list: "watch.list"
+      off: "watch.toggle"
     }, (verb, input) => verb === "off" ? { ...input, watching: false } : input)
   },
+  {
+    name: "watch_get",
+    title: "Read one watch status",
+    description: "Check whether you watch one Thread, Artifact, or Topic. It cannot start or stop a watch or change notifications.",
+    inputSchema: {
+      targetType: exports_external.enum(["thread", "artifact", "topic"]).describe("what to check"),
+      targetId: exports_external.string().describe("the id (thr_/art_/top_)")
+    },
+    surfaces: ["mcp"],
+    toolset: "loop",
+    run: forward("watch.get")
+  },
+  {
+    name: "watch_list",
+    title: "List your watches",
+    description: "List every Thread, Artifact, and Topic you currently watch. It cannot start or stop a watch or change notifications.",
+    inputSchema: {},
+    surfaces: ["mcp"],
+    toolset: "loop",
+    run: forward("watch.list")
+  },
   {
     name: "watch_target",
     title: "Watch a thread/artifact/topic",
@@ -18393,10 +18702,10 @@ var ACTION_DEFINITIONS = [
   },
   {
     name: "artifact",
-    title: "Durable artifacts",
-    description: "Durable, versioned artifacts — the team's living documents (AD-201). Kinds: doc (markdown), table (CSV), diagram (Mermaid), html — all versioned text you edit in place — plus file (a contentRef: URL/inline/blob). " + "verb=create (kind+type+title+summary, source for text kinds / contentRef for file; summary is the required one-line skim/retrieval description; a text artifact is born at v1 and is AUTOMATICALLY listed on its sourceThreadId thread — no link post needed). " + "For computer-produced output, create with the computerSessionId returned by attach_computer so the artifact cites the reproducible session. " + "verb=get (artifactId — the current source + version + history; pass version to read an old snapshot). " + "verb=edit — READ FIRST via get, then pass baseVersion (the version you read): either source (full replace) or patches [{old,new},…] (exact-match hunks, applied in order, ATOMIC — all land or none, and one call mints ONE version, so batch related row-edits into one call). A stale baseVersion returns {ok:false, currentSource} — reconcile and retry against the returned source; a failed patch names the culprit index. " + "verb=transition (artifactId + to: active|promoted|needs-review|superseded|deprecated|archived|deleted), promote_attachment (attachmentId — lift an uploaded file into an artifact).",
+    title: "Create or edit an Artifact",
+    description: "Create or edit a durable, versioned Artifact, or promote a Thread attachment into one. Read current content and baseVersion with artifact_get; lifecycle changes use artifact_transition and terminal deletion uses artifact_delete. " + "Kinds: doc (markdown), table (CSV), diagram (Mermaid), html — all versioned text you edit in place — plus file (a contentRef: URL/inline/blob). " + "verb=create (kind+type+title+summary, source for text kinds / contentRef for file; summary is the required one-line skim/retrieval description; a text artifact is born at v1 and is AUTOMATICALLY listed on its sourceThreadId thread — no link post needed). " + "For computer-produced output, create with the computerSessionId returned by attach_computer so the artifact cites the reproducible session. " + "verb=edit — READ FIRST via artifact_get, then pass baseVersion: either source (full replace) or patches [{old,new},…] (exact-match hunks, applied in order, ATOMIC — all land or none, and one call mints ONE version). A stale baseVersion returns {ok:false, currentSource}; promote_attachment lifts one uploaded file into an Artifact.",
     inputSchema: {
-      verb: exports_external.enum(["create", "get", "edit", "transition", "promote_attachment"]).describe("which artifact move"),
+      verb: exports_external.enum(["create", "edit", "promote_attachment"]).describe("which artifact move"),
       title: exports_external.string().optional().describe("create: the artifact's title"),
       kind: exports_external.enum(["doc", "table", "diagram", "html", "file"]).optional().describe("create: structural kind (default file). doc/table/diagram/html are editable text"),
       type: exports_external.string().optional().describe("create: semantic type, e.g. decision|summary|plan|markdown|table|research-brief"),
@@ -18407,25 +18716,57 @@ var ACTION_DEFINITIONS = [
       sourceThreadId: exports_external.string().optional().describe("create: the thread it came from"),
       computerSessionId: exports_external.string().optional().describe("create: the attached computer session that produced it, cms_…"),
       sourceContributionIds: exports_external.array(exports_external.string()).optional().describe("create: contributions it distills"),
-      artifactId: exports_external.string().optional().describe("get/edit/transition: the artifact, art_…"),
-      version: exports_external.number().optional().describe("get: read this old snapshot instead of the current"),
+      artifactId: exports_external.string().optional().describe("edit: the Artifact, art_…"),
       baseVersion: exports_external.number().optional().describe("edit: the version you READ (from get/create) — stale base is rejected with the current source"),
       patches: exports_external.array(exports_external.object({ old: exports_external.string(), new: exports_external.string() })).optional().describe("edit: exact-match hunks applied in order, atomically; each old must match exactly once"),
       note: exports_external.string().optional().describe("edit: one-line summary of what changed"),
-      to: exports_external.string().optional().describe("transition: the target status"),
-      reason: exports_external.string().optional().describe("transition: why"),
       attachmentId: exports_external.string().optional().describe("promote_attachment: the upload, att_…")
     },
     surfaces: ["mcp"],
     toolset: "artifacts",
     run: dispatch({
       create: "artifact.create",
-      get: "artifact.get",
       edit: "artifact.edit",
-      transition: "artifact.transition",
       promote_attachment: "attachment.promote"
     }, (verb, input) => verb === "edit" ? { ...input, verb: Array.isArray(input.patches) ? "patch" : "replace" } : input)
   },
+  {
+    name: "artifact_get",
+    title: "Read an Artifact",
+    description: "Read an Artifact's current source, version, immutable history, and AppBundle references, or pass version for an older snapshot. It cannot edit content, change lifecycle, promote an attachment, or delete an Artifact.",
+    inputSchema: {
+      artifactId: exports_external.string().describe("the Artifact, art_…"),
+      version: exports_external.number().optional().describe("read this old snapshot instead of the current")
+    },
+    surfaces: ["mcp"],
+    toolset: "artifacts",
+    run: forward("artifact.get")
+  },
+  {
+    name: "artifact_transition",
+    title: "Change an Artifact's lifecycle",
+    description: "Move one Artifact to active, promoted, needs-review, superseded, deprecated, or archived. Terminal deletion is isolated in artifact_delete.",
+    inputSchema: {
+      artifactId: exports_external.string().describe("the Artifact, art_…"),
+      to: exports_external.enum(["active", "promoted", "needs-review", "superseded", "deprecated", "archived"]).describe("the target lifecycle state"),
+      reason: exports_external.string().optional().describe("why the lifecycle changed")
+    },
+    surfaces: ["mcp"],
+    toolset: "artifacts",
+    run: forward("artifact.transition")
+  },
+  {
+    name: "artifact_delete",
+    title: "Permanently delete an Artifact",
+    description: "Move one Artifact into its terminal deleted lifecycle state so it leaves every read and retrieval surface. This cannot be reversed through the Artifact lifecycle.",
+    inputSchema: {
+      artifactId: exports_external.string().describe("the Artifact to permanently delete, art_…"),
+      reason: exports_external.string().optional().describe("why the Artifact must be deleted")
+    },
+    surfaces: ["mcp"],
+    toolset: "artifacts",
+    run: (ex, input) => ex.call("artifact.transition", { ...input, to: "deleted" })
+  },
   {
     name: "apps",
     title: "List visible Apps",
@@ -18438,57 +18779,22 @@ var ACTION_DEFINITIONS = [
     run: forward("app.list")
   },
   {
-    name: "apps",
-    title: "Publish and manage Apps",
-    description: "Manage stable Arbor Apps through one guarded lifecycle (AD-248/249). verb=list shows Apps across the actor's Spaces plus active listed public Apps across the organization; get reads the active release, pending control intent, state generation, and history; create mints the Space-owned identity; deploy health-checks an immutable AppBundle without moving the URL; deployment inspects one candidate; activate and rollback reserve an attributed intent before provider health and compare-and-swap completion; set_access changes Space/public and public discovery immediately; reset_state is the only durable SQLite deletion and resumes partial failure with the same idempotency key; archive stops serving but retains history. Read with get immediately before activate, rollback, access, or reset. Public Apps must be public+(unlisted|listed)+none; durable Apps are space+durable.",
+    name: "app_list",
+    title: "List visible Apps",
+    description: "READ ONLY: List Apps visible to you, including authorized archived Apps when requested. It cannot modify App state, deployment state, access, or durable SQLite.",
     inputSchema: {
-      verb: exports_external.enum([
-        "list",
-        "get",
-        "create",
-        "deploy",
-        "deployment",
-        "activate",
-        "rollback",
-        "set_access",
-        "reset_state",
-        "archive"
-      ]).describe("which App lifecycle operation to perform"),
-      includeArchived: exports_external.boolean().optional().describe("list: include authorized archived Apps"),
-      appId: exports_external.string().optional().describe("required for every verb except list and create: the App, app_…"),
-      spaceId: exports_external.string().optional().describe("create: owning Space, spc_…"),
-      title: exports_external.string().min(1).max(160).optional().describe("create: short factual title"),
-      slug: exports_external.string().min(1).max(59).optional().describe("create: stable label in app-<slug>.arborthreads.dev"),
-      access: exports_external.enum(["space", "public"]).optional().describe("create/set_access: gateway access"),
-      discovery: exports_external.enum(["unlisted", "listed"]).nullable().optional().describe("create/set_access: public discovery; Space Apps use null"),
-      stateMode: exports_external.enum(["none", "durable"]).optional().describe("create: none or Space-only isolated durable SQLite"),
-      bundleId: exports_external.string().optional().describe("deploy: verified immutable AppBundle, bnd_…"),
-      deploymentId: exports_external.string().optional().describe("deployment/activate/rollback: deployment, dep_…"),
-      expectedActiveDeploymentId: exports_external.string().nullable().optional().describe("activate/rollback: active deployment just read; null only for first activation"),
-      expectedGeneration: exports_external.number().int().min(0).optional().describe("reset_state: durable generation just read"),
-      idempotencyKey: exports_external.string().min(1).max(200).optional().describe("deploy/reset_state: stable key for this one logical mutation")
+      includeArchived: exports_external.boolean().optional().describe("include archived Apps you are authorized to inspect")
     },
     surfaces: ["mcp"],
     toolset: "apps",
-    run: dispatch({
-      list: "app.list",
-      get: "app.get",
-      create: "app.create",
-      deploy: "app.deploy",
-      deployment: "app.deployment_get",
-      activate: "app.activate",
-      rollback: "app.rollback",
-      set_access: "app.set_access",
-      reset_state: "app.reset_state",
-      archive: "app.archive"
-    })
+    run: forward("app.list")
   },
   {
     name: "app_get",
     title: "Read an App",
-    description: "Inspect one App's stable URL, active release, pending control intent, source AppBundle, attributed deployment timeline, last activation health, state identity/generation, and reset history. Read this before deployment, rollback, access, or state changes so compare-and-swap inputs are current.",
+    description: "READ ONLY: Inspect one App's stable URL, active deployment, pending control intent, deployment history, health, and durable state generation. It cannot modify App state, deployment state, access, or durable SQLite; use its activeDeploymentId as app_activate's expectedActiveDeploymentId.",
     inputSchema: { appId: exports_external.string().describe("the App, app_…") },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.get")
   },
@@ -18504,7 +18810,7 @@ var ACTION_DEFINITIONS = [
       discovery: exports_external.enum(["unlisted", "listed"]).nullable().optional().describe("public Apps only; default unlisted"),
       stateMode: exports_external.enum(["none", "durable"]).describe("durable allocates Space-only isolated facet SQLite; deployment never resets it")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.create")
   },
@@ -18517,7 +18823,7 @@ var ACTION_DEFINITIONS = [
       bundleId: exports_external.string().describe("verified immutable AppBundle, bnd_…"),
       idempotencyKey: exports_external.string().min(1).max(200).describe("stable key for this one logical deployment attempt")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.deploy")
   },
@@ -18533,6 +18839,18 @@ var ACTION_DEFINITIONS = [
     toolset: "apps",
     run: forward("app.deployment_get")
   },
+  {
+    name: "app_deployment_get",
+    title: "Inspect an App deployment",
+    description: "READ ONLY: Inspect one deployment's candidate, active, failed, or superseded state, source AppBundle, provider receipt, and redacted health result. It cannot modify App state, deployment state, access, or durable SQLite.",
+    inputSchema: {
+      appId: exports_external.string().describe("owning App, app_…"),
+      deploymentId: exports_external.string().describe("deployment, dep_…")
+    },
+    surfaces: ["mcp"],
+    toolset: "apps",
+    run: forward("app.deployment_get")
+  },
   {
     name: "app_activate",
     title: "Activate a verified deployment",
@@ -18542,20 +18860,20 @@ var ACTION_DEFINITIONS = [
       deploymentId: exports_external.string().describe("verified candidate, dep_…"),
       expectedActiveDeploymentId: exports_external.string().nullable().describe("active deployment from app_get, or null before first activation")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.activate")
   },
   {
     name: "app_rollback",
     title: "Roll back App code",
-    description: "Re-activate a superseded deployment while preserving the App's state identity and SQLite data. Durable rollback is refused when the target bundle cannot read the current state schema; reset is a separate destructive operation.",
+    description: "Re-activate a superseded deployment while preserving the App's state identity and SQLite data. Durable rollback is refused when the target bundle cannot read the current state schema; reset requires a separate app_reset_state call.",
     inputSchema: {
       appId: exports_external.string().describe("target App, app_…"),
       deploymentId: exports_external.string().describe("superseded deployment to restore, dep_…"),
       expectedActiveDeploymentId: exports_external.string().describe("current active deployment from app_get")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.rollback")
   },
@@ -18568,7 +18886,7 @@ var ACTION_DEFINITIONS = [
       access: exports_external.enum(["space", "public"]).describe("new gateway access"),
       discovery: exports_external.enum(["unlisted", "listed"]).nullable().optional().describe("required concept only for public Apps")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.set_access")
   },
@@ -18581,16 +18899,16 @@ var ACTION_DEFINITIONS = [
       expectedGeneration: exports_external.number().int().min(0).describe("state generation from app_get"),
       idempotencyKey: exports_external.string().min(1).max(200).describe("stable key for this one deliberate reset")
     },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.reset_state")
   },
   {
     name: "app_archive",
     title: "Archive an App",
-    description: "Remove an App from active serving while retaining its stable identity, deployment timeline, receipts, and durable state for audit/recovery. Archive is lifecycle-only: it neither resets state nor deletes release history.",
+    description: "Remove an App from active serving while retaining its stable identity, deployment timeline, receipts, durable state, and release history for audit and recovery. Archive is a lifecycle-only transition.",
     inputSchema: { appId: exports_external.string().describe("target App, app_…") },
-    surfaces: ["cli"],
+    surfaces: ["mcp", "cli"],
     toolset: "apps",
     run: forward("app.archive")
   },
@@ -18635,7 +18953,9 @@ var ACTIONS = ACTION_DEFINITIONS.map((action) => {
   const outputSchema = outputSchemaFor(action.name);
   if (!outputSchema)
     throw new Error(`${action.name}: MCP action is missing an output schema`);
-  return { ...action, outputSchema };
+  const annotations = mcpAnnotationsFor(action.name);
+  const description = annotations.readOnlyHint && !action.description.startsWith("READ ONLY") ? `READ ONLY: ${action.description}` : action.description;
+  return { ...action, description, outputSchema, annotations };
 });
 
 // src/config.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "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",