@lambdacurry/arbor 0.20.21 → 0.20.23

package/dist/arbor.js

@@ -16725,14 +16725,14 @@ var recallHit = exports_external.looseObject({
   score: exports_external.number(),
   excerpt: exports_external.string(),
   space: spaceRef.nullable(),
-  url: exports_external.string(),
+  url: nullableString,
   createdAt: timestamp
 });
 var contributionRef = exports_external.looseObject({
   id,
   objectType: exports_external.string(),
   excerpt: exports_external.string(),
-  url: exports_external.string(),
+  url: nullableString,
   createdAt: timestamp,
   space: spaceRef.nullable(),
   crossSpace: exports_external.boolean()
@@ -18193,7 +18193,7 @@ var CONTRIBUTION_ADD_LINK_RELS = [
 ];
 var ORIENTATION = `Arbor is your team's deliberation room and shared memory — people and agents settle typed work here, and Arbor remembers what's decided. To work well:
 
-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. In a large Space, don't search the whole org by habit: use \`tree\` to choose the room, then scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. 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 durable contribution lanes that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full lane list live. A lane is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.
+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. In a large Space, don't search the whole org by habit: use \`tree\` to choose the room, then scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. 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 durable contribution lanes that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full lane list live. A lane is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.
 2. CONTRIBUTE typed points — but ADD ONLY WHAT'S ADDITIVE (AD-205). Ask what the most additive move is, not whether to say something: if your reaction to a point already on the record fits in one line — agree OR disagree — STAMP it (vouch, or push back with a one-line why), don't restate it; if you'd only echo consensus, reviewing IS the contribution and staying out is fine. When you DO contribute, it's ONE point, with the type that names your move (proposal / critique / question / evidence / risk / correction / assertion / decision). Markdown welcome; put references IN your prose (a URL or [label](#con_…) becomes a navigable reference). Prose refs are CITATIONS — they never move your contribution in the thread, so cite freely; to REPLY under a specific contribution, pass links: [{rel: 'inReplyTo', targetId}] (AD-196). WHY: a thread where every agent restates the consensus is noise — the record is strongest when each point appears ONCE and gets vouched (or contested) with a stamp, not re-said; and one typed point is reviewable on its own, so a synthesis citing five points should read as the most top-level thing in the thread, not as a reply to the first one it mentions.
 3. ANSWER through requests. When \`inbox\` or a thread shows an open request you can meet, answer THROUGH it — \`respond\` to it, or \`stamp\` the contribution a review request is about — so it completes and the requester is notified. WHY: a plain reply that merely happens to answer leaves their request hanging (the most common failure).
 4. REVIEW honestly; promote the standout, sparingly. \`stamp\` to vouch or push back with a one-line why (you can't stamp your own work — request a review via \`request\`). PROMOTE a contribution/artifact only when it's the standout the org should find FIRST (the \uD83C\uDF96️). One deliberate exception (AD-200): in a STANDING thread, periodically promoting a distilling synthesis IS the job — it's how an open-forever lane compresses for newcomers and recall, not applause inflation; promoting your own synthesis there is fine (only stamps bar self-review). WHY: promotion is curation, not applause — and it's about an OUTPUT, never a whole thread (a thread RESOLVES; it is never "promoted").
@@ -18225,6 +18225,7 @@ function dispatch(map2, reshape) {
     return ex.call(op, reshape && verb ? reshape(verb, rest) : rest);
   };
 }
+var NOTIFICATION_TRIAGE_DESCRIPTION = "READ ONLY: List your awareness feed newest first with unseen count and derived triage class: `settled-context` = settled Thread context; `owed-by-me` = an open request pointing to `inbox`; `judgment-available` = live engagement inviting judgment; `closed-loop` = your request completed; `room-motion` = ambient activity. Notifications are FYI, not a second obligation surface: `inbox` alone contains work owed by you; this cannot mark notifications read or modify inbox obligations.";
 var PAGINATION_INPUT = {
   limit: exports_external.number().int().min(1).optional().describe("max items to return — enables pagination"),
   cursor: exports_external.string().optional().describe("opaque cursor from a prior response's nextCursor (use with --limit)")
@@ -18300,7 +18301,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "recall",
     title: "Recall existing knowledge",
-    description: "Search Arbor for what's already known before you re-derive an answer — returns ranked prior contributions, artifacts, and decisions scoped to your org. When you know the room, especially in a large Space, pass space/topic/thread to keep recall inside that working set before deeper reads.",
+    description: "READ ONLY: Search Arbor semantically for existing contributions, artifacts, and decisions. Use `tree` for lifecycle/attention routing; once you know the area, pass space/topic/thread to keep recall inside that working set before targeted reads.",
     inputSchema: {
       query: exports_external.string().min(1).describe("what you want to recall, in natural language"),
       space: exports_external.string().optional().describe("optional space id to scope the search"),
@@ -18610,7 +18611,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_receipt",
     title: "Read a run receipt",
-    description: "READ ONLY: Inspect one Run's durable receipt during or after execution when you need purpose, placement, durability, recoverable operation state, activity, or terminal outcome. Returns compact Run history and assessments, including durable operation receipts, not raw command transcripts or process output.",
+    description: "READ ONLY: Inspect one Run's durable receipt during or after execution, including its Run-owned operation/activity state; use this instead of parent computer_status to establish whether an isolated Run still has work in flight. Returns compact history/assessments and durable operation receipts, not raw command transcripts or process output.",
     inputSchema: {
       runId: exports_external.string().describe("the run to read, run_… (from computer_run_start or computer_runs)")
     },
@@ -18681,7 +18682,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_status",
     title: "Inspect a computer",
-    description: "READ ONLY: Inspect live Computer capabilities, runtime/process state, and the declared profile when computer_open did not answer a current operational question. Use get_computer instead for durable recipe, generation, and snapshot lineage.",
+    description: "READ ONLY: Inspect the live PARENT Thread Computer's capabilities, runtime/process state, and declared profile. This does not report isolated Run command state; use computer_run_receipt for a Run's operations, or get_computer for durable recipe/generation/snapshot lineage.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…")
     },
@@ -19154,7 +19155,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "notifications",
     title: "List your notifications",
-    description: "List the awareness feed of activity involving you — stamps on your work, replies in your threads, @-mentions, and your completed requests — newest first, with an unseen count. Each item carries a triage `class` (AD-182) derived from thread state: `settled-context` (thread resolved — durable context, never live work), `owed-by-me` (an open ask targets you — go to `inbox`, this row is just a pointer), `judgment-available` (your work was engaged in a live thread — an invitation, not an obligation), `closed-loop` (your ask completed), `room-motion` (ambient activity, safely skippable). This is FYI (no response owed); `inbox` remains the only obligation surface.",
+    description: NOTIFICATION_TRIAGE_DESCRIPTION,
     inputSchema: { ...PAGINATION_INPUT },
     surfaces: ["cli"],
     toolset: "loop",
@@ -19246,11 +19247,11 @@ var ACTION_DEFINITIONS = [
   {
     name: "tree",
     title: "Navigate the workspace tree",
-    description: "READ ONLY: Map Spaces to Topics to Threads for orientation; Topic nodes carry lifecycle density (total/current Threads, health, requests, latest activity) without expanding Threads, lanesForYou shows where your skills fit, and thread depth adds openRequestsForYou/standouts. In a large Space, choose the relevant Topic here, then scope recall to that Topic/Thread before targeted reads instead of inflating the map.",
+    description: "READ ONLY: Map Spaces to Topics to Threads for orientation; Topic `activeThreadCount` is the current working set (active/stuck/needs-review/standing), while `status` is area attention (`stuck`=any stuck, `attention`=needs-review or open request, `healthy`=neither), not personal obligation (`inbox`). In a large Space, choose the Topic here, scope recall to it, then read only the returned Thread/Artifact; expand tree or use topic_get only for explicit enumeration or Topic-wide context.",
     inputSchema: {
       space: exports_external.string().optional().describe("scope to one space id (spc_…)"),
       topic: exports_external.string().optional().describe("scope to one topic id (top_…)"),
-      depth: exports_external.enum(["spaces", "topics", "threads"]).optional().describe("how deep to expand: spaces (just spaces) | topics (default: + topics + light roster) | threads (+ each topic's threads). For one topic's threads or one thread's contributions, prefer topic_get / thread_get.")
+      depth: exports_external.enum(["spaces", "topics", "threads"]).optional().describe("how deep to expand: spaces (just spaces) | topics (default: + topics + light roster) | threads (+ each topic's threads). For a concrete question in one Topic, prefer Topic-scoped recall; use topic_get when you intentionally need its Thread roster or Topic-wide context.")
     },
     surfaces: ["mcp", "cli"],
     toolset: "loop",
@@ -19526,7 +19527,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "topic_get",
     title: "Read a topic",
-    description: "READ ONLY: Read a Topic's details, guidance, parent+topic contribution lanes, Threads, open requests, and promoted artifacts. Use it to zoom into one area after tree; it cannot modify Topic state.",
+    description: "READ ONLY: Read a Topic's full details, guidance, complete Thread roster, open requests, and promoted artifacts. Use it for intentional Topic-wide context or enumeration; for a concrete question in a large Topic, prefer Topic-scoped recall first.",
     inputSchema: {
       topicId: exports_external.string().min(1).describe("the topic id")
     },
@@ -19706,7 +19707,7 @@ var ACTION_DEFINITIONS = [
   {
     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.",
+    description: NOTIFICATION_TRIAGE_DESCRIPTION,
     inputSchema: { ...PAGINATION_INPUT },
     surfaces: ["mcp"],
     toolset: "loop",
@@ -20910,21 +20911,24 @@ function commandHelp(positionals) {
   const specs = flagsForSchema(action.inputSchema);
   const explicitPositionals = positionalSpecs(action);
   const primary = explicitPositionals.length === 0 ? primaryPositionalField(action.inputSchema) : undefined;
-  const positionalFlags = new Set(explicitPositionals.map((spec) => spec.flag));
+  const helpPositionals = explicitPositionals.length > 0 ? explicitPositionals : primary ? [primary] : [];
+  const positionalFlags = new Set(helpPositionals.map((spec) => spec.flag));
   const usageFlags = specs.filter((spec) => !positionalFlags.has(spec.flag)).map((f) => {
     const token = f.kind === "boolean" ? `--${f.flag}` : `--${f.flag} <${f.kind}>`;
     return f.required ? token : `[${token}]`;
   }).join(" ");
-  const explicitArgs = explicitPositionals.map((spec) => spec.required ? ` <${spec.field}>` : ` [<${spec.field}>]`).join("");
-  const usage = `Usage: arbor ${commandWords(action)}${explicitArgs}${primary ? ` [<${primary.field}>]` : ""}${usageFlags ? ` ${usageFlags}` : ""}`;
+  const usageArgs = helpPositionals.map((spec) => spec.required ? ` <${spec.field}>` : ` [<${spec.field}>]`).join("");
+  const usage = `Usage: arbor ${commandWords(action)}${usageArgs}${usageFlags ? ` ${usageFlags}` : ""}`;
   const lines = specs.map((f) => {
-    const req = f.required ? "required" : "optional";
+    const positional = helpPositionals.find((spec) => spec.flag === f.flag);
+    const req = positional ? positional.required ? `alternative to <${positional.field}> positional; input required` : `alternative to [<${positional.field}>] positional; input optional` : f.required ? "required" : "optional";
+    const value = f.kind === "boolean" ? `--${f.flag} [<boolean>]` : `--${f.flag} <${f.kind}>`;
     const fileNote = f.kind === "string" ? ` (or --${f.flag}-file <path|->)` : "";
     const desc = f.description ? ` — ${f.description}` : "";
     const listNote = f.kind === "array" ? f.literal ? `
       list: repeat --${f.flag} per item; a single value is ONE item (commas kept literal)` : `
       list: repeat --${f.flag} per item, or one comma-separated value (--${f.flag} a,b,c)` : "";
-    return `  --${f.flag} <${f.kind}>  [${req}]${fileNote}${desc}${listNote}`;
+    return `  ${value}  [${req}]${fileNote}${desc}${listNote}`;
   });
   const primaryNote = primary ? `
 
@@ -21197,7 +21201,7 @@ async function renderMe(ctx, action) {
 ` : "") + spaceLines;
   emitDual(me, human, action, ctx);
 }
-var CLI_NOTE = `On this CLI, before your first write: commands are NOUN-VERB (\`thread get\`, \`space get\`, not \`get thread\`). The underscore tool-names you see in MCP, recall, and docs (\`set_space_charter\`, \`transition_thread\`) work as CLI commands VERBATIM too — \`set_space_charter …\` and \`set space charter …\` are the same command, either form. Computer work is one parallel family: start project work with \`arbor computer open --thread-id thr_…\`, keep its cms_… receipt, then pass it as \`--computer-session-id\` to later tools. Checkpoint intermediate complete units; \`computer stop\` performs the final checkpoint before teardown. Internal Currybox grants are exchanged per call and never printed. A public screenshot is lighter: \`arbor computer verify --thread-id thr_… --target-url https://…\` runs directly, with no open/checkpoint/stop ceremony, and returns a gated download URL plus ready-to-place Markdown; put that Markdown where the image belongs in the contribution body and pass the matching attachment id. A single-argument command also takes a bare positional — \`recall "your question"\`, \`thread get thr_…\` — so you don't have to name the obvious flag. Flag names are kebab-derived from the inputs (\`--thread-id\`, \`--request-id\`, \`--contribution-id\` — not \`--thread\`/\`--request\`), so check \`arbor help\` or \`arbor <command> --help\` (now focused on that command's flags) instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (1-2 short sentences, hard limit 500 chars) on a long contribution becomes its recall snippet. List inputs always accept a REPEATED flag, one item each (\`--guidance "…" --guidance "…"\`) — the form that works everywhere. A single value additionally comma-splits for TOKEN lists (\`--capabilities a,b,c\`), but stays one literal item for PROSE lists (\`--guidance\`, \`--ways-to-help\`, \`--contribution-lanes\`) so a comma inside a sentence can't shred it; \`arbor <command> --help\` names which form each list flag takes. \`tree\` is a glanceable map (default depth \`topics\`); drill down with \`space get\`/\`topic get\`/\`thread get\` rather than expanding the whole tree. If \`inbox\` is empty, that's "nothing needs you" — but if you're unsure your auth resolved, \`whoami\` confirms it.`;
+var CLI_NOTE = `On this CLI, before your first write: commands are NOUN-VERB (\`thread get\`, \`space get\`, not \`get thread\`). The underscore tool-names you see in MCP, recall, and docs (\`set_space_charter\`, \`transition_thread\`) work as CLI commands VERBATIM too — \`set_space_charter …\` and \`set space charter …\` are the same command, either form. Computer work is one parallel family: start project work with \`arbor computer open --thread-id thr_…\`, keep its cms_… receipt, then pass it as \`--computer-session-id\` to later tools. Checkpoint intermediate complete units; \`computer stop\` performs the final checkpoint before teardown. Internal Currybox grants are exchanged per call and never printed. A public screenshot is lighter: \`arbor computer verify --thread-id thr_… --target-url https://…\` runs directly, with no open/checkpoint/stop ceremony, and returns a gated download URL plus ready-to-place Markdown; put that Markdown where the image belongs in the contribution body and pass the matching attachment id. A single-argument command also takes a bare positional — \`recall "your question"\`, \`thread get thr_…\` — so you don't have to name the obvious flag. Flag names are kebab-derived from the inputs (\`--thread-id\`, \`--request-id\`, \`--contribution-id\` — not \`--thread\`/\`--request\`), so check \`arbor help\` or \`arbor <command> --help\` (now focused on that command's flags) instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (1-2 short sentences, hard limit 500 chars) on a long contribution becomes its recall snippet. List inputs always accept a REPEATED flag, one item each (\`--guidance "…" --guidance "…"\`) — the form that works everywhere. A single value additionally comma-splits for TOKEN lists (\`--capabilities a,b,c\`), but stays one literal item for PROSE lists (\`--guidance\`, \`--ways-to-help\`, \`--contribution-lanes\`) so a comma inside a sentence can't shred it; \`arbor <command> --help\` names which form each list flag takes. \`tree\` is the lifecycle map (default depth \`topics\`): choose a Topic, then \`recall --topic top_… "your question"\` before targeted \`thread get\`/\`artifact get\`; use \`topic get\` or deeper tree only when you intentionally need Topic-wide context or enumeration. If \`inbox\` is empty, that's "nothing needs you" — but if you're unsure your auth resolved, \`whoami\` confirms it.`;
 function renderOrient(ctx) {
   emitDual({ orientation: ORIENTATION, cliNote: CLI_NOTE }, `${ORIENTATION}
 

package/package.json

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