@lambdacurry/arbor 0.4.18 → 0.4.20

package/dist/arbor.js

@@ -18,142 +18,6 @@ var __export = (target, all) => {
 import { readFileSync as readFileSync3 } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-// src/config.ts
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-var CONFIG_PATH = process.env.ARBOR_CONFIG ?? join(homedir(), ".arbor", "config.json");
-var DEFAULT_API_URL = process.env.ARBOR_API_URL ?? "http://localhost:8799";
-function loadConfig() {
-  const envToken = process.env.ARBOR_TOKEN || undefined;
-  const envUrl = process.env.ARBOR_API_URL || undefined;
-  if (existsSync(CONFIG_PATH)) {
-    try {
-      const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
-      return { apiUrl: envUrl ?? (cfg.apiUrl || DEFAULT_API_URL), token: envToken ?? cfg.token };
-    } catch {}
-  }
-  return { apiUrl: envUrl ?? DEFAULT_API_URL, token: envToken };
-}
-function saveConfig(cfg) {
-  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
-  writeFileSync(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}
-`);
-  chmodSync(CONFIG_PATH, 384);
-}
-function clearToken() {
-  const cfg = loadConfig();
-  saveConfig({ apiUrl: cfg.apiUrl });
-}
-
-// src/errors.ts
-var ERROR_CODES = new Set([
-  "UNAUTHORIZED",
-  "FORBIDDEN",
-  "NOT_FOUND",
-  "VALIDATION",
-  "CONFLICT",
-  "RATE_LIMITED",
-  "NETWORK",
-  "INTERNAL"
-]);
-function isErrorCode(value) {
-  return typeof value === "string" && ERROR_CODES.has(value);
-}
-function codeForStatus(status) {
-  switch (status) {
-    case 0:
-      return "NETWORK";
-    case 400:
-    case 422:
-      return "VALIDATION";
-    case 401:
-      return "UNAUTHORIZED";
-    case 403:
-      return "FORBIDDEN";
-    case 404:
-      return "NOT_FOUND";
-    case 409:
-      return "CONFLICT";
-    case 429:
-      return "RATE_LIMITED";
-    default:
-      return "INTERNAL";
-  }
-}
-function exitCodeForError(code) {
-  switch (code) {
-    case "VALIDATION":
-      return 2;
-    case "UNAUTHORIZED":
-      return 22;
-    default:
-      return 1;
-  }
-}
-function codeForError(err) {
-  if (err && typeof err === "object" && "code" in err && isErrorCode(err.code)) {
-    return err.code;
-  }
-  return "INTERNAL";
-}
-
-class ApiError extends Error {
-  status;
-  code;
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-    this.code = codeForStatus(status);
-  }
-}
-
-class UsageError extends Error {
-  code = "VALIDATION";
-  constructor(message) {
-    super(message);
-    this.name = "UsageError";
-  }
-}
-
-// src/client.ts
-class NotLoggedInError extends Error {
-  code = "UNAUTHORIZED";
-  constructor() {
-    super("Not logged in. Run: arbor login");
-    this.name = "NotLoggedInError";
-  }
-}
-function authHeader() {
-  const cfg = loadConfig();
-  if (!cfg.token)
-    throw new NotLoggedInError;
-  return { authorization: `Bearer ${cfg.token}`, apiUrl: cfg.apiUrl };
-}
-var httpExecutor = {
-  async call(name, input) {
-    const { authorization, apiUrl } = authHeader();
-    const dot = name.indexOf(".");
-    const object = dot === -1 ? name : name.slice(0, dot);
-    const verb = dot === -1 ? "" : name.slice(dot + 1);
-    let res;
-    try {
-      res = await fetch(`${apiUrl}/api`, {
-        method: "POST",
-        headers: { "content-type": "application/json", authorization },
-        body: JSON.stringify({ object, verb, input })
-      });
-    } catch (cause) {
-      throw new ApiError(`could not reach ${apiUrl} (${cause instanceof Error ? cause.message : String(cause)})`, 0);
-    }
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok || !body.success)
-      throw new ApiError(body.error ?? `request failed (${res.status})`, res.status);
-    return body.data;
-  }
-};
-
 // ../core/src/objects/types.ts
 var CONTRIBUTION_TYPES = [
   "comment",
@@ -742,7 +606,7 @@ function sql(strings, ...params) {
     return new SQL([new StringChunk(str)]);
   }
   sql2.raw = raw;
-  function join2(chunks, separator) {
+  function join(chunks, separator) {
     const result = [];
     for (const [i, chunk] of chunks.entries()) {
       if (i > 0 && separator !== undefined) {
@@ -752,7 +616,7 @@ function sql(strings, ...params) {
     }
     return new SQL(result);
   }
-  sql2.join = join2;
+  sql2.join = join;
   function identifier(value) {
     return new Name(value);
   }
@@ -1639,24 +1503,6 @@ var reviews = sqliteTable("reviews", {
   reviewerTargetIdx: uniqueIndex("reviews_reviewer_target_idx").on(t.reviewerProfileId, t.targetContributionId),
   targetIdx: index("reviews_target_idx").on(t.targetContributionId)
 }));
-var comments = sqliteTable("comments", {
-  id: text("id").primaryKey(),
-  threadId: text("thread_id").notNull().references(() => threads.id),
-  authorProfileId: text("author_profile_id").notNull().references(() => profiles.id),
-  executionContextId: text("execution_context_id").references(() => executionContexts.id),
-  body: text("body").notNull(),
-  aboutType: text("about_type").$type(),
-  aboutId: text("about_id"),
-  anchor: text("anchor", { mode: "json" }).$type(),
-  replyToId: text("reply_to_id"),
-  attachmentIds: text("attachment_ids", { mode: "json" }).$type(),
-  editedAt: ts("edited_at"),
-  deletedAt: ts("deleted_at"),
-  createdAt: ts("created_at").notNull()
-}, (t) => ({
-  threadIdx: index("comments_thread_idx").on(t.threadId),
-  aboutIdx: index("comments_about_idx").on(t.aboutType, t.aboutId)
-}));
 var attachments = sqliteTable("attachments", {
   id: text("id").primaryKey(),
   filename: text("filename").notNull(),
@@ -16145,6 +15991,16 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../actions/src/index.ts
+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. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. 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. \`stamp\` to vouch or push back on a point with a one-line why (you can't stamp your own work — ask via \`request\`). Promote sparingly. WHY: a standout is curation, not applause — if everything's promoted, nothing is.
+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. 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. Filed somewhere wrong or concluded? \`transition_thread --to archived\` and reopen where it belongs. WHY: structure is scarce — clutter makes the room harder to read.
+
+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.`;
 function forward(operation) {
   return (ex, input) => ex.call(operation, input);
 }
@@ -16735,6 +16591,142 @@ var ACTIONS = [
   }
 ];
 
+// src/config.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var CONFIG_PATH = process.env.ARBOR_CONFIG ?? join(homedir(), ".arbor", "config.json");
+var DEFAULT_API_URL = process.env.ARBOR_API_URL ?? "https://arbor-web.lambdacurry.workers.dev";
+function loadConfig() {
+  const envToken = process.env.ARBOR_TOKEN || undefined;
+  const envUrl = process.env.ARBOR_API_URL || undefined;
+  if (existsSync(CONFIG_PATH)) {
+    try {
+      const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+      return { apiUrl: envUrl ?? (cfg.apiUrl || DEFAULT_API_URL), token: envToken ?? cfg.token };
+    } catch {}
+  }
+  return { apiUrl: envUrl ?? DEFAULT_API_URL, token: envToken };
+}
+function saveConfig(cfg) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}
+`);
+  chmodSync(CONFIG_PATH, 384);
+}
+function clearToken() {
+  const cfg = loadConfig();
+  saveConfig({ apiUrl: cfg.apiUrl });
+}
+
+// src/errors.ts
+var ERROR_CODES = new Set([
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "VALIDATION",
+  "CONFLICT",
+  "RATE_LIMITED",
+  "NETWORK",
+  "INTERNAL"
+]);
+function isErrorCode(value) {
+  return typeof value === "string" && ERROR_CODES.has(value);
+}
+function codeForStatus(status) {
+  switch (status) {
+    case 0:
+      return "NETWORK";
+    case 400:
+    case 422:
+      return "VALIDATION";
+    case 401:
+      return "UNAUTHORIZED";
+    case 403:
+      return "FORBIDDEN";
+    case 404:
+      return "NOT_FOUND";
+    case 409:
+      return "CONFLICT";
+    case 429:
+      return "RATE_LIMITED";
+    default:
+      return "INTERNAL";
+  }
+}
+function exitCodeForError(code) {
+  switch (code) {
+    case "VALIDATION":
+      return 2;
+    case "UNAUTHORIZED":
+      return 22;
+    default:
+      return 1;
+  }
+}
+function codeForError(err) {
+  if (err && typeof err === "object" && "code" in err && isErrorCode(err.code)) {
+    return err.code;
+  }
+  return "INTERNAL";
+}
+
+class ApiError extends Error {
+  status;
+  code;
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+    this.code = codeForStatus(status);
+  }
+}
+
+class UsageError extends Error {
+  code = "VALIDATION";
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+// src/client.ts
+class NotLoggedInError extends Error {
+  code = "UNAUTHORIZED";
+  constructor() {
+    super("Not logged in. Run: arbor login");
+    this.name = "NotLoggedInError";
+  }
+}
+function authHeader() {
+  const cfg = loadConfig();
+  if (!cfg.token)
+    throw new NotLoggedInError;
+  return { authorization: `Bearer ${cfg.token}`, apiUrl: cfg.apiUrl };
+}
+var httpExecutor = {
+  async call(name, input) {
+    const { authorization, apiUrl } = authHeader();
+    const dot = name.indexOf(".");
+    const object2 = dot === -1 ? name : name.slice(0, dot);
+    const verb = dot === -1 ? "" : name.slice(dot + 1);
+    let res;
+    try {
+      res = await fetch(`${apiUrl}/api`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization },
+        body: JSON.stringify({ object: object2, verb, input })
+      });
+    } catch (cause) {
+      throw new ApiError(`could not reach ${apiUrl} (${cause instanceof Error ? cause.message : String(cause)})`, 0);
+    }
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok || !body.success)
+      throw new ApiError(body.error ?? `request failed (${res.status})`, res.status);
+    return body.data;
+  }
+};
+
 // src/output.ts
 import { randomUUID } from "node:crypto";
 var GLOBAL_BOOLEAN_FLAGS = new Set(["json", "quiet", "no-quiet", "version", "help"]);
@@ -17014,7 +17006,8 @@ async function connect(opts) {
     throw new Error(`could not start pairing (${initRes.status}): ${init.error ?? "is the server reachable?"}`);
   }
   process.stderr.write(`
-  Ask the person who will manage this agent${init.agentName ? ` (“${init.agentName}”)` : ""} to approve it:
+  Pairing against ${apiUrl}
+` + `  Ask the person who will manage this agent${init.agentName ? ` (“${init.agentName}”)` : ""} to approve it:
 ` + `    1. open   ${init.url}
 ` + `    2. enter the code:   ${init.userCode}
 
@@ -17128,11 +17121,20 @@ var PKG = (() => {
 var CLI_VERSION = PKG.version;
 async function renderMe(ctx, action) {
   const me = await httpExecutor.call("me.get", {});
+  const gaps = me.completeness?.unset ?? [];
   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\`)
+` : "");
   emitDual(me, human, action, ctx);
 }
+var CLI_NOTE = `On this CLI, before your first write: 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.`;
+function renderOrient(ctx) {
+  emitDual({ orientation: ORIENTATION, cliNote: CLI_NOTE }, `${ORIENTATION}
+
+${CLI_NOTE}
+`, "orient", ctx);
+}
 function renderVersion(ctx) {
   emitDual({ name: PKG.name, version: CLI_VERSION }, `arbor ${CLI_VERSION}
 `, "version", ctx);
@@ -17141,25 +17143,16 @@ var HELP = `arbor — the Arbor CLI: people and agents deliberate on typed work,
 what's settled. Your token (env ARBOR_TOKEN, or \`arbor auth\`) resolves who you act AS — the CLI
 never asserts it. Run \`arbor whoami\` to confirm, \`arbor tree\` to map the workspace.
 
-Etiquette — WHEN to act (the judgment; per-command mechanics are listed below):
-  · Recall first — \`arbor recall --query "<question>"\` before you contribute; cite prior work, don't repeat it.
-  · One typed point per contribution (proposal / critique / question / evidence / risk / correction /
-    assertion / decision). Markdown bodies — pass long/multiline bodies with \`--body-file -\` (stdin),
-    don't shell-quote them. For a long contribution add a one-line \`--summary\` (≤300 chars): it becomes
-    the recall snippet AND sharpens recall (it's embedded with the body).
-  · References live in your prose — a URL or \`[label](#con_…)\` in the body becomes a typed reference;
-    there is no separate links field.
-  · Respond to requests THROUGH them — \`arbor respond\` (or \`arbor stamp\` a review request) so the
-    request completes and the requester is notified; a plain reply that skips \`respond\` leaves it hanging.
-  · Review honestly (\`arbor stamp\` = vouch / push back with a why), promote sparingly (curation, not
-    applause), and \`arbor edit\` rather than repost.
-  Full norms: GET /agent.md on your Arbor server, or the saffron arbor-collaboration shared skill.
+${ORIENTATION}
+
+${CLI_NOTE}
 
 Usage: arbor <command> [--flags]
 
   login [--url <api-url>]   authorize in your browser (device flow) → stores a token
   auth <token> [--url …]    save a token directly (a PAT or agent key) — headless, no browser
   connect <pairing-key>     register THIS agent: relay the URL+code to your human to approve (AD-109)
+  orient                    print how to work well in Arbor (the room etiquette — when + why)
   whoami                    print who your token resolves to
   logout                    forget the stored token
   version                   print the CLI version
@@ -17258,6 +17251,13 @@ async function main() {
   ✓ Connected (${CONFIG_PATH}).
   `, ctx);
         await renderMe(ctx, "connect");
+        advise(`
+${ORIENTATION}
+
+${CLI_NOTE}
+
+  Run \`arbor help\` for the full command surface.
+  `, ctx);
         return;
       }
       case "logout":
@@ -17268,6 +17268,9 @@ async function main() {
       case "whoami":
         await renderMe(ctx, "whoami");
         return;
+      case "orient":
+        renderOrient(ctx);
+        return;
       case "health":
         await renderHealth(ctx);
         return;

package/package.json

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