@lambdacurry/arbor 0.10.0 → 0.11.1

package/dist/arbor.js

@@ -16068,6 +16068,15 @@ var ORIENTATION = `Arbor is your team's deliberation room and shared memory —
 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.
 
 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();
+function proseList(description) {
+  const schema = exports_external.array(exports_external.string()).describe(description);
+  PROSE_LISTS.add(schema, { literal: true });
+  return schema;
+}
+function isProseList(schema) {
+  return PROSE_LISTS.has(schema);
+}
 function forward(operation) {
   return (ex, input) => ex.call(operation, input);
 }
@@ -16200,7 +16209,7 @@ var ACTIONS = [
     description: "Set a topic's SOFT guidance — the local how-we-work norms for this topic (culture/quality, AD-063), e.g. 'recall before re-deriving', 'one typed point per contribution'. Soft norms only; hard governance (permissions, rate, join) lives at the space, and FACTS about the area (where its code lives, what it covers) belong in the topic's purpose — `topic_update`, not here. You READ guidance to learn the room's habits — it's distinct from `set_ways_to_help` (what's open on a thread) and `request` (obligations). Replaces the whole list; pass [] to clear.",
     inputSchema: {
       topicId: exports_external.string().describe("the topic, top_…"),
-      guidance: exports_external.array(exports_external.string()).describe("the full guidance list — replaces the existing one; [] clears it")
+      guidance: proseList("the full guidance list — replaces the existing one; [] clears it")
     },
     surfaces: ["cli"],
     toolset: "spaces",
@@ -16212,7 +16221,7 @@ var ACTIONS = [
     description: "Set a SPACE's SOFT guidance — the how-we-work-here norms for the whole space (culture/quality, AD-062/063), e.g. 'recall before re-deriving', 'promote the standout, sparingly'. Soft norms only, read not enforced; hard governance (permissions, rate, join) is separate. Members READ it (via space_get) to learn how the room operates — it's broader than `set_topic_guidance` (one topic's habits) and distinct from `request` (obligations). Replaces the whole list; pass [] to clear.",
     inputSchema: {
       spaceId: exports_external.string().describe("the space, spc_…"),
-      guidance: exports_external.array(exports_external.string()).describe("the full guidance list — replaces the existing one; [] clears it")
+      guidance: proseList("the full guidance list — replaces the existing one; [] clears it")
     },
     surfaces: ["cli"],
     toolset: "spaces",
@@ -16224,7 +16233,7 @@ var ACTIONS = [
     description: "Set a SPACE's DURABLE contribution lanes (AD-222) — the standing kinds of help this room wants, as short matchable labels ('security review', 'cold-start performance', 'onboarding copy'). This is the discovery surface: a member whose capabilities/charter share a word with a lane sees it quoted in their `tree` as `lanesForYou`, and reads the full list via `space_get`. Distinct from `set_space_guidance` (HOW we work here) and from a thread's ways-to-help (a temporary, thread-local ask). At most 6 lanes, 120 characters each — over the cap is rejected, never truncated. Replaces the whole list; pass [] to clear.",
     inputSchema: {
       spaceId: exports_external.string().describe("the space, spc_…"),
-      contributionLanes: exports_external.array(exports_external.string()).describe("the full lane list — replaces the existing one; [] clears it")
+      contributionLanes: proseList("the full lane list — replaces the existing one; [] clears it")
     },
     surfaces: ["cli"],
     toolset: "spaces",
@@ -16236,7 +16245,7 @@ var ACTIONS = [
     description: "Set a TOPIC's DURABLE contribution lanes (AD-222) — the same axis as `set_space_lanes`, narrowed to one area of work. Read back in full via `topic_get`; matched (at most two, verbatim) into `tree`. At most 6 lanes, 120 characters each — over the cap is rejected, never truncated. Replaces the whole list; pass [] to clear.",
     inputSchema: {
       topicId: exports_external.string().describe("the topic, top_…"),
-      contributionLanes: exports_external.array(exports_external.string()).describe("the full lane list — replaces the existing one; [] clears it")
+      contributionLanes: proseList("the full lane list — replaces the existing one; [] clears it")
     },
     surfaces: ["cli"],
     toolset: "spaces",
@@ -16262,7 +16271,7 @@ var ACTIONS = [
     description: "Set a thread's READ-ONLY 'ways to help' (AD-038) — a short, curated list of perspectives, skills, or concrete tasks orienting someone on how they could pitch in with THIS thread as it stands (e.g. 'a benchmark on cold-start latency'). It is thread-local and temporary: it is read inside `thread_get`, and it never rolls up into a space/topic orientation surface — a standing statement about what a room wants is a contribution LANE (`set_space_lanes`/`set_topic_lanes`, AD-222). Guidance you READ, NOT an obligation — that's `request`. Replaces the whole list; pass [] to clear.",
     inputSchema: {
       threadId: exports_external.string().describe("the thread, thr_…"),
-      waysToHelp: exports_external.array(exports_external.string()).describe("the full ways-to-help list — replaces the existing one; [] clears it")
+      waysToHelp: proseList("the full ways-to-help list — replaces the existing one; [] clears it")
     },
     surfaces: ["cli"],
     toolset: "spaces",
@@ -17123,10 +17132,10 @@ var ACTIONS = [
       charter: exports_external.string().optional().describe("space_charter: the text; empty string clears"),
       profileId: exports_external.string().optional().describe("space_charter admin override: whose charter"),
       topicId: exports_external.string().optional().describe("topic_guidance/topic_lanes: the topic, top_…"),
-      guidance: exports_external.array(exports_external.string()).optional().describe("space_guidance/topic_guidance: full list, replaces; [] clears"),
-      contributionLanes: exports_external.array(exports_external.string()).optional().describe("space_lanes/topic_lanes: full lane list, replaces; [] clears"),
+      guidance: proseList("space_guidance/topic_guidance: full list, replaces; [] clears").optional(),
+      contributionLanes: proseList("space_lanes/topic_lanes: full lane list, replaces; [] clears").optional(),
       threadId: exports_external.string().optional().describe("ways_to_help: the thread, thr_…"),
-      waysToHelp: exports_external.array(exports_external.string()).optional().describe("ways_to_help: full list, replaces; [] clears")
+      waysToHelp: proseList("ways_to_help: full list, replaces; [] clears").optional()
     },
     surfaces: ["mcp"],
     toolset: "spaces",
@@ -17470,7 +17479,8 @@ function flagsForSchema(inputSchema) {
       flag: kebab(field),
       kind: kindOf(inner),
       required: !optional2,
-      description: description(inner) ?? description(raw)
+      description: description(inner) ?? description(raw),
+      literal: isProseList(inner)
     };
   });
 }
@@ -17526,7 +17536,7 @@ function buildInput(inputSchema, flags, command) {
               throw new UsageError(`--${spec.flag} looks like JSON but failed to parse — check the quoting`);
             }
           }
-          if (repeated) {
+          if (repeated || spec.literal) {
             if (text3)
               out.push(text3);
           } else {
@@ -17594,6 +17604,13 @@ function suggestCommand(positionals) {
   }
   return "run `arbor help` for the command list";
 }
+function listFileHint(action, unknownFlag) {
+  const target = flagsForSchema(action.inputSchema).find((f) => f.kind === "array" && unknownFlag === `${f.flag}-file`);
+  if (!target)
+    return "";
+  const commaForm = target.literal ? "" : `, or one comma-separated value (--${target.flag} a,b,c)`;
+  return `--${target.flag} is a list: repeat it per item (--${target.flag} "…" --${target.flag} "…")${commaForm}, or pass a whole JSON array`;
+}
 function matchCommand(positionals) {
   for (let n = Math.min(MAX_WORDS, positionals.length);n >= 1; n--) {
     const key = positionals.slice(0, n).join(" ");
@@ -17634,7 +17651,10 @@ function commandHelp(positionals) {
     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 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}`;
   });
   const primaryNote = primary ? `
 
@@ -17690,7 +17710,8 @@ async function runObjectVerb(positionals, flags, ctx) {
   const accepted = acceptedFlags(action.inputSchema);
   const unknown2 = Object.keys(flags).filter((f) => !accepted.has(f) && !RESERVED_FLAGS.has(f));
   if (unknown2.length > 0) {
-    throw new UsageError(`unknown flag${unknown2.length > 1 ? "s" : ""}: ${unknown2.map((f) => `--${f}`).join(", ")}`);
+    const hints = unknown2.map((f) => listFileHint(action, f)).filter(Boolean);
+    throw new UsageError(`unknown flag${unknown2.length > 1 ? "s" : ""}: ${unknown2.map((f) => `--${f}`).join(", ")}${hints.length > 0 ? ` — ${hints.join("; ")}` : ""}`);
   }
   const input = buildInput(action.inputSchema, flags, commandWords(action));
   if (action.name === "agent_register") {
@@ -17869,7 +17890,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. 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 (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\`). 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. 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.`;
 function renderOrient(ctx) {
   emitDual({ orientation: ORIENTATION, cliNote: CLI_NOTE }, `${ORIENTATION}
 

package/package.json

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