@lambdacurry/arbor 0.4.26 → 0.4.28

package/dist/arbor.js

@@ -16003,8 +16003,8 @@ var ORIENTATION = `Arbor is your team's deliberation room and shared memory —
 
 1. RECALL FIRST. 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. WHY: a room where everyone re-derives is just a chat log.
 2. CONTRIBUTE typed points — ONE point per contribution, 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 — there's no separate links field). WHY: one typed point is reviewable on its own.
-3. ANSWER through asks. When \`inbox\` or a thread shows an open request you can meet, answer THROUGH it — \`respond\` to it, or \`stamp\` the contribution a review-ask is about — so it completes and the requester is notified. WHY: a plain reply that merely happens to answer leaves their ask 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 — ask via \`request\`). PROMOTE a contribution/artifact only when it's the standout the org should find FIRST (the \uD83C\uDF96️). WHY: promotion is curation, not applause — and it's about an OUTPUT, never a whole thread (a thread RESOLVES; it is never "promoted").
+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️). WHY: promotion is curation, not applause — and it's about an OUTPUT, never a whole thread (a thread RESOLVES; it is never "promoted").
 5. EDIT, don't repost. \`edit\` your own contribution to sharpen it; the record stays audited. A genuinely different point is a NEW contribution.
 6. OPEN STRUCTURE sparingly, and CLOSE it when done. Check \`tree\` first and prefer an existing thread; \`create_topic\`/\`create_thread\` only when work truly doesn't fit, named by its OBJECTIVE with your first contribution. When a thread reaches its conclusion, \`transition_thread --to resolved\` (done); if it was opened in the wrong place, \`--to archived\` and reopen where it belongs. WHY: structure is scarce — both clutter AND open threads no one closes make the room harder to read.
 
@@ -16211,12 +16211,12 @@ var ACTIONS = [
   },
   {
     name: "request",
-    title: "Ask for a review",
-    description: "Request a review of work in a thread — name targets (an inbox item each) or leave it open (the thread board). Use this when you need someone's eyes to move forward; completion is software-computed from their responses (first | quorum(n) | all-targets | deadline | explicit). Review-only (AD-130): a review placed on the contribution it's about counts as a response.",
+    title: "Request a contribution or review",
+    description: "Request input on a thread (AD-161). Two kinds, picked by `aboutContributionId`: OMIT it to request a CONTRIBUTION — new input on the thread (evidence, a proposal, a counter-argument), met by someone's `respond` contribution. PASS it to request a REVIEW of that specific contribution, met by a `stamp` on it. Either way, name targets (an inbox item each) or leave it open (the thread board); completion is software-computed from their responses (first | quorum(n) | all-targets | deadline | explicit).",
     inputSchema: {
       threadId: exports_external.string().describe("the thread the request is in, thr_…"),
-      requestedAction: exports_external.string().optional().describe("a one-line 'what'"),
-      aboutContributionId: exports_external.string().optional().describe("card-scoped request: the contribution this is about, con_… (must be in the thread; badges that card)"),
+      requestedAction: exports_external.string().optional().describe("a one-line 'what you're requesting'"),
+      aboutContributionId: exports_external.string().optional().describe("PASS to request a REVIEW of this contribution (con_…, in the thread; met by a stamp, badges that card). OMIT to request a CONTRIBUTION on the thread (met by a respond)."),
       targetProfileIds: exports_external.array(exports_external.string()).optional().describe("targeted recipients (omit → open board)"),
       completion: exports_external.enum(["first", "quorum", "all-targets", "deadline", "explicit"]),
       quorumN: exports_external.number().int().min(1).optional().describe("required when completion=quorum"),
@@ -16355,7 +16355,7 @@ var ACTIONS = [
   {
     name: "members",
     title: "List the people + agents in your org",
-    description: "List everyone in your org — humans and agents — with their profile id, identity, role, and self-declared capabilities. Reach for this to find WHO to route work to: the profile id to @-mention in a contribution, or to target a `request` at a specific person (e.g. ask Meg for a design review). Read-only.",
+    description: "List everyone in your org — humans and agents — with their profile id, identity, role, and self-declared capabilities. Reach for this to find WHO to route work to: the profile id to @-mention in a contribution, or to target a `request` at a specific person (e.g. request a review from Meg). Read-only.",
     inputSchema: {},
     surfaces: ["mcp", "cli"],
     run: forward("org.members")
@@ -16876,6 +16876,9 @@ function readTextSource(src) {
   }
   return text3.replace(/[\r\n]+$/, "");
 }
+function primaryPositionalField(inputSchema) {
+  return flagsForSchema(inputSchema).find((f) => f.required && (f.kind === "string" || f.kind === "number"));
+}
 function flagsForSchema(inputSchema) {
   return Object.entries(inputSchema).map(([field, raw]) => {
     const { inner, optional: optional2 } = unwrapOptional(raw);
@@ -16981,6 +16984,35 @@ function helpLine(action) {
 }
 var COMMAND_HELP = CLI_ACTIONS.map(helpLine).join(`
 `);
+function commandHelp(positionals) {
+  const match = matchCommand(positionals);
+  if (!match)
+    return;
+  const { action } = match;
+  const specs = flagsForSchema(action.inputSchema);
+  const primary = primaryPositionalField(action.inputSchema);
+  const usageFlags = specs.map((f) => {
+    const token = f.kind === "boolean" ? `--${f.flag}` : `--${f.flag} <${f.kind}>`;
+    return f.required ? token : `[${token}]`;
+  }).join(" ");
+  const usage = `Usage: arbor ${commandWords(action)}${primary ? ` [<${primary.field}>]` : ""}${usageFlags ? ` ${usageFlags}` : ""}`;
+  const lines = specs.map((f) => {
+    const req = f.required ? "required" : "optional";
+    const fileNote = f.kind === "string" ? ` (or --${f.flag}-file <path|->)` : "";
+    const desc = f.description ? ` — ${f.description}` : "";
+    return `  --${f.flag} <${f.kind}>  [${req}]${fileNote}${desc}`;
+  });
+  const primaryNote = primary ? `
+
+A single bare argument fills --${primary.flag} (e.g. \`arbor ${commandWords(action)} <${primary.field}>\`).` : "";
+  return `${commandWords(action)} — ${action.description}
+
+${usage}
+
+${lines.join(`
+`)}${primaryNote}
+`;
+}
 function commandCatalog() {
   return CLI_ACTIONS.map((action) => ({
     command: commandWords(action),
@@ -16999,7 +17031,21 @@ async function runObjectVerb(positionals, flags, ctx) {
   const match = matchCommand(positionals);
   if (!match)
     throw new UsageError(`unknown command: ${positionals.join(" ") || "(none)"}`);
-  const { action } = match;
+  const { action, words } = match;
+  const extras = positionals.slice(words);
+  if (extras.length > 0) {
+    const primary = primaryPositionalField(action.inputSchema);
+    if (!primary) {
+      throw new UsageError(`unexpected argument: ${extras[0]} (\`${commandWords(action)}\` takes no positional — use flags)`);
+    }
+    if (extras.length > 1) {
+      throw new UsageError(`too many arguments: \`${commandWords(action)}\` takes one positional (--${primary.flag}); pass the rest as flags`);
+    }
+    if (flags[primary.flag] !== undefined || flags[`${primary.flag}-file`] !== undefined) {
+      throw new UsageError(`pass --${primary.flag} either as a flag or as the positional argument, not both`);
+    }
+    flags[primary.flag] = extras[0];
+  }
   const accepted = acceptedFlags(action.inputSchema);
   const unknown2 = Object.keys(flags).filter((f) => !accepted.has(f) && !RESERVED_FLAGS.has(f));
   if (unknown2.length > 0) {
@@ -17155,13 +17201,18 @@ async function renderMe(ctx, action) {
   const spaceLines = spaceGaps.length > 0 ? `  spaces without your charter (say how you operate there):
 ` + spaceGaps.map((s) => `    • ${s.spaceTitle} — \`set_space_charter --space-id ${s.spaceId} --charter "…"\`
 `).join("") : "";
+  const charter = me.profile.description?.trim();
+  const caps = me.profile.capabilities ?? [];
+  const setLines = (charter ? `  charter: ${charter}
+` : "") + (caps.length > 0 ? `  capabilities: ${caps.join(", ")}
+` : "");
   const human = `${me.profile.displayName} · ${me.profile.kind} · org-role ${me.profile.orgRole}
 ` + `  org ${me.profile.orgId} · resolved via ${me.client.kind}
-` + (gaps.length > 0 ? `  to be more legible to your team, set: ${gaps.join("; ")} (\`introduce\`)
+` + setLines + (gaps.length > 0 ? `  to be more legible to your team, set: ${gaps.join("; ")} (\`introduce\`)
 ` : "") + 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\`). 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\` for a command's exact flags instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (≤300 chars) on a long contribution becomes its recall snippet. List inputs (e.g. \`--capabilities\`) accept EITHER a comma list (\`--capabilities a,b,c\`) OR a repeated flag (\`--capabilities a --capabilities b\`) — both build the array. \`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\`). 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\` (≤300 chars) on a long contribution becomes its recall snippet. List inputs (e.g. \`--capabilities\`) accept EITHER a comma list (\`--capabilities a,b,c\`) OR a repeated flag (\`--capabilities a --capabilities b\`) — both build the array. \`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.`;
 function renderOrient(ctx) {
   emitDual({ orientation: ORIENTATION, cliNote: CLI_NOTE }, `${ORIENTATION}
 
@@ -17248,7 +17299,11 @@ async function main() {
       return;
     }
     if (truthyFlag(flags.help)) {
-      renderHelp(ctx);
+      const focused = positionals.length > 0 ? commandHelp(positionals) : undefined;
+      if (focused)
+        emitDual({ help: focused }, focused, "help", ctx);
+      else
+        renderHelp(ctx);
       return;
     }
     switch (cmd) {

package/package.json

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