@primitive.ai/prim 0.1.0-alpha.20 → 0.1.0-alpha.22

package/README.md

@@ -58,9 +58,14 @@ graph, conflicting edits are gated, and presence is reported. Each hook
 self-resolves the CLI at run time (PATH, then a local install, then
 `npx --yes @latest`), so it keeps working with no global install.
 
+Installs into the current project by default — the repo's `.claude/settings.json`
+/ `.codex/hooks.json`, resolved from the git root (so any subdirectory works);
+pass `--scope user` to install machine-wide.
+
 ```bash
-prim claude install    # Install Claude Code hooks   (uninstall / status)
-prim codex install     # Install OpenAI Codex hooks   (uninstall / status)
+prim claude install                # Install Claude Code hooks (project scope; uninstall / status)
+prim claude install --scope user   # Install machine-wide instead
+prim codex install                 # Install OpenAI Codex hooks (project scope)
 ```
 
 ### Daemon
@@ -113,6 +118,12 @@ and offers to install into `.husky/`.
 prim statusline        # Render the team-presence statusline (reads the daemon)
 ```
 
+### Welcome
+
+```bash
+prim welcome           # Brief orientation to the decision graph (shown after setup)
+```
+
 ### Session & journal
 
 Lower-level plumbing for the capture pipeline — org binding and the local move

package/SKILL.md

@@ -67,6 +67,16 @@ npx --yes @primitive.ai/prim decisions confirm <idOrShortId>
 
 Confirmations are author-targeted and rare by design; answering keeps the graph's rationale trustworthy. Don't manufacture rationale — if you don't know why a decision was made, say so.
 
+## Author a decision deliberately
+
+Capture is automatic for the decisions you *make while coding*. When the user instead asks you to **record a decision explicitly** — one that didn't fall out of an edit (a design call, a convention, a choice settled in discussion) — author it directly:
+
+```
+npx --yes @primitive.ai/prim decisions create --intent "Adopt prosemirror-collab over Yjs" --area data --rationale "Server-authoritative ordering" --alternatives "Yjs,Automerge"
+```
+
+Only `--intent` is required. Optional: `--kind` (change|exploration|task_execution|unclear, default change), `--rationale`, `--area`, `--decided`, `--alternatives` (comma-separated), `--confidence` (high|medium|low, default high), `--reversibility` (high|low, default high), and `--files` (comma-separated repo-relative paths the decision governs — pass these to make the conflict gate fire on later edits to those files, same path form as `decisions check`). STDOUT is the created identity `{ decisionId, shortId, createdAt }`; STDERR prints `[prim] created dec_<short>.` — pass that `dec_<short>` straight into `decisions show` / `cascade` / `confirm`. Author on the user's behalf only when they ask for a decision to be recorded; don't narrate your own routine edits into the graph (the hooks already do that).
+
 ## Presence
 
 With the daemon running (`npx --yes @primitive.ai/prim daemon start`), `npx --yes @primitive.ai/prim daemon status` includes the live online count in its STDOUT JSON (when presence is fresh); Claude Code surfaces it in the statusline as `team: N online`. Your captured decisions are attributed to your agent automatically -- no flag required.
@@ -108,7 +118,7 @@ Examples:
 - **An "unavailable" / "not verified" gate or check is not an all-clear.** Treat constraints as UNKNOWN and proceed deliberately; never read the silence as approval.
 - **A `deny` means a real prior decision conflicts.** Reconcile only when you genuinely intend to override it; otherwise pick an approach that respects it.
 - **Reconcile bypasses are single-use and short-lived.** One bypass clears your *next* edit to the governed file; it is not a standing override.
-- **Capture is automatic, never manual.** If decisions aren't showing up, check that the session hooks are installed (`claude status` / `codex status`) and the daemon is running — don't try to inject moves by hand.
+- **Capture of your coding activity is automatic, never manual.** If decisions aren't showing up, check that the session hooks are installed (`claude status` / `codex status`) and the daemon is running — don't try to inject moves by hand. (Deliberately *authoring* a decision the user asks you to record is a separate, supported path — `decisions create`, above.)
 - **Don't fabricate rationale on a confirmation.** If you don't know why a decision was made, say so rather than guessing.
 
 ## After each task

package/dist/{chunk-BEEGFDGU.js → chunk-4QJOQIY6.js}

@@ -11,6 +11,7 @@ var ANSI_CODES = {
   gray: "\x1B[90m"
 };
 var ANSI_RESET = "\x1B[0m";
+var ANSI_DIM = "\x1B[2m";
 var ANSI_BOLD = "\x1B[1m";
 function supportsColor() {
   if (process.env.NO_COLOR !== void 0 && process.env.NO_COLOR !== "") {
@@ -24,6 +25,12 @@ function color(text, c) {
   }
   return `${ANSI_CODES[c]}${text}${ANSI_RESET}`;
 }
+function dim(text) {
+  if (!supportsColor()) {
+    return text;
+  }
+  return `${ANSI_DIM}${text}${ANSI_RESET}`;
+}
 function bold(text) {
   if (!supportsColor()) {
     return text;
@@ -53,6 +60,7 @@ function stripAnsi(text) {
 
 export {
   color,
+  dim,
   bold,
   colorForArea,
   stripAnsi

package/dist/daemon/server.js

@@ -27,6 +27,7 @@ var client = getClient();
 var activeSessionId = process.env.PRIM_DAEMON_SESSION_ID ?? `daemon-${process.pid}`;
 var lastHeartbeatAt;
 var lastOnlineCount;
+var lastOnlineNames;
 var lastOkAtLocal;
 var heartbeatTimer;
 var tokenCheckTimer;
@@ -70,9 +71,8 @@ async function sendHeartbeat() {
       if (typeof result.lastHeartbeatAt === "number") {
         lastHeartbeatAt = result.lastHeartbeatAt;
       }
-      if (typeof result.onlineCount === "number") {
-        lastOnlineCount = result.onlineCount;
-      }
+      lastOnlineCount = typeof result.onlineCount === "number" ? result.onlineCount : void 0;
+      lastOnlineNames = Array.isArray(result.onlineNames) ? result.onlineNames : void 0;
     }
   } catch (err) {
     process.stderr.write(
@@ -123,9 +123,10 @@ function handleStatusSnapshot() {
     uptimeMs: Date.now() - startedAt,
     sessionId: activeSessionId,
     lastHeartbeatAt,
-    // Withhold a frozen count once it's no longer fresh; the statusline shows
-    // "presence: stale" rather than a confident, wrong "team: N".
+    // Withhold a frozen count/names once they're no longer fresh; the
+    // statusline shows "presence: stale" rather than a confident, wrong list.
     onlineCount: presenceFresh ? lastOnlineCount : void 0,
+    onlineNames: presenceFresh ? lastOnlineNames : void 0,
     presenceStale
   };
 }

package/dist/hooks/post-tool-use.js

@@ -2,7 +2,7 @@
 import {
   bold,
   color
-} from "../chunk-BEEGFDGU.js";
+} from "../chunk-4QJOQIY6.js";
 import {
   getClient
 } from "../chunk-26VA3ADF.js";

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import {
+  bold,
   color,
   colorForArea,
+  dim,
   stripAnsi
-} from "./chunk-BEEGFDGU.js";
+} from "./chunk-4QJOQIY6.js";
 import {
   checkAffectedDecisions,
   daemonOrDirectGet,
@@ -279,6 +281,7 @@ async function exchangeCode(siteUrl, code, codeVerifier, redirectUri) {
 }
 
 // src/commands/claude-install.ts
+import { execSync } from "child_process";
 import {
   closeSync,
   existsSync as existsSync3,
@@ -368,7 +371,17 @@ var PRIM_BINS = [
 ];
 var JSON_INDENT = 2;
 var USER_SCOPE_PATH = join2(homedir(), ".claude", "settings.json");
-var PROJECT_SCOPE_PATH = join2(process.cwd(), ".claude", "settings.json");
+function projectRoot() {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+var projectScopePath = () => join2(projectRoot(), ".claude", "settings.json");
 var CAPTURE_EVENTS = [
   "SessionStart",
   "UserPromptSubmit",
@@ -389,7 +402,7 @@ var REGISTRATIONS = [
   makeRegistration("SessionEnd", "*", SESSION_END_BIN)
 ];
 function settingsPathFor(scope) {
-  return scope === "user" ? USER_SCOPE_PATH : PROJECT_SCOPE_PATH;
+  return scope === "user" ? USER_SCOPE_PATH : projectScopePath();
 }
 function readSettings(path) {
   if (!existsSync3(path)) {
@@ -546,15 +559,15 @@ function performStatus() {
       statusline: statuslineInstalled(settings)
     };
   };
-  return { user: statusFor(USER_SCOPE_PATH), project: statusFor(PROJECT_SCOPE_PATH) };
+  return { user: statusFor(USER_SCOPE_PATH), project: statusFor(projectScopePath()) };
 }
 function resolveScope(input) {
-  if (input === void 0 || input === "user") {
-    return "user";
-  }
-  if (input === "project") {
+  if (input === void 0 || input === "project") {
     return "project";
   }
+  if (input === "user") {
+    return "user";
+  }
   console.error(`[prim] unknown --scope "${input}" (expected: user or project)`);
   process.exit(1);
 }
@@ -562,7 +575,7 @@ function registerClaudeCommands(program2) {
   const claude = program2.command("claude").description("Manage the prim Claude Code integration (capture, gate, ingest, presence)");
   claude.command("install").description("Register the prim hooks + statusline in Claude Code's settings.json").option(
     "--scope <scope>",
-    "user (default, ~/.claude/settings.json) or project (./.claude/settings.json)"
+    "project (default, the repo's .claude/settings.json) or user (~/.claude/settings.json)"
   ).option("--force", "Replace any drifted prim hook entries").action((opts) => {
     const scope = resolveScope(opts.scope);
     const result = performInstall(scope, opts.force ?? false);
@@ -579,7 +592,7 @@ function registerClaudeCommands(program2) {
   });
   claude.command("uninstall").description("Remove all prim hooks + the prim statusline from settings.json").option(
     "--scope <scope>",
-    "user (default, ~/.claude/settings.json) or project (./.claude/settings.json)"
+    "project (default, the repo's .claude/settings.json) or user (~/.claude/settings.json)"
   ).action((opts) => {
     const scope = resolveScope(opts.scope);
     const result = performUninstall(scope);
@@ -627,9 +640,9 @@ var CODEX_REGISTRATIONS = [
   makeRegistration("SessionStart", "*", SESSION_START_BIN2, CODEX_ARGS)
 ];
 var USER_SCOPE_PATH2 = join3(homedir2(), ".codex", "hooks.json");
-var PROJECT_SCOPE_PATH2 = join3(process.cwd(), ".codex", "hooks.json");
+var projectScopePath2 = () => join3(projectRoot(), ".codex", "hooks.json");
 function settingsPathFor2(scope) {
-  return scope === "user" ? USER_SCOPE_PATH2 : PROJECT_SCOPE_PATH2;
+  return scope === "user" ? USER_SCOPE_PATH2 : projectScopePath2();
 }
 function applyInstall2(settings, options = {}) {
   const hooks = { ...settings.hooks ?? {} };
@@ -694,24 +707,24 @@ function performStatus2() {
     const settings = readSettings(path);
     return { path, gate: isGateInstalled2(settings), capture: captureInstalled2(settings) };
   };
-  return { user: statusFor(USER_SCOPE_PATH2), project: statusFor(PROJECT_SCOPE_PATH2) };
+  return { user: statusFor(USER_SCOPE_PATH2), project: statusFor(projectScopePath2()) };
 }
 function resolveScope2(input) {
-  if (input === void 0 || input === "user") {
-    return "user";
-  }
-  if (input === "project") {
+  if (input === void 0 || input === "project") {
     return "project";
   }
+  if (input === "user") {
+    return "user";
+  }
   console.error(`[prim] unknown --scope "${input}" (expected: user or project)`);
   process.exit(1);
 }
 var TRUST_NOTICE = "[prim] Codex requires hook trust: run `/hooks` in Codex to review and trust these hooks (or start Codex with --dangerously-bypass-hook-trust). Until trusted, the hooks will not fire.";
 function registerCodexCommands(program2) {
   const codex = program2.command("codex").description("Manage the prim Codex integration (capture, gate, ingest, presence)");
-  codex.command("install").description("Register the prim hooks in Codex's ~/.codex/hooks.json").option(
+  codex.command("install").description("Register the prim hooks in Codex's hooks.json (project scope by default)").option(
     "--scope <scope>",
-    "user (default, ~/.codex/hooks.json) or project (./.codex/hooks.json)"
+    "project (default, the repo's .codex/hooks.json) or user (~/.codex/hooks.json)"
   ).option("--force", "Replace any drifted prim hook entries").action((opts) => {
     const scope = resolveScope2(opts.scope);
     const result = performInstall2(scope, opts.force ?? false);
@@ -723,9 +736,9 @@ function registerCodexCommands(program2) {
     console.error(TRUST_NOTICE);
     console.log(JSON.stringify(result, null, JSON_INDENT2));
   });
-  codex.command("uninstall").description("Remove all prim hooks from ~/.codex/hooks.json").option(
+  codex.command("uninstall").description("Remove all prim hooks from Codex's hooks.json").option(
     "--scope <scope>",
-    "user (default, ~/.codex/hooks.json) or project (./.codex/hooks.json)"
+    "project (default, the repo's .codex/hooks.json) or user (~/.codex/hooks.json)"
   ).action((opts) => {
     const scope = resolveScope2(opts.scope);
     const result = performUninstall2(scope);
@@ -751,6 +764,22 @@ import { spawn } from "child_process";
 import { existsSync as existsSync4, readFileSync as readFileSync4, unlinkSync } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join4 } from "path";
+
+// src/lib/presence.ts
+function formatTeammates(names, cap) {
+  if (names === void 0) {
+    return "\u2014";
+  }
+  if (names.length === 0) {
+    return "just you";
+  }
+  if (names.length <= cap) {
+    return names.join(", ");
+  }
+  return `${names.slice(0, cap).join(", ")} +${String(names.length - cap)}`;
+}
+
+// src/commands/daemon.ts
 var DAEMON_BIN = "prim-daemon-server";
 var PID_PATH = join4(homedir3(), ".config", "prim", "daemon.pid");
 var SOCK_PATH = join4(homedir3(), ".config", "prim", "sock");
@@ -924,8 +953,9 @@ async function daemonStatus() {
   } else if (!snapshot) {
     process.stderr.write("[prim] \u2713 daemon live (no snapshot)\n");
   } else {
+    const team = snapshot.onlineNames !== void 0 ? ` \xB7 team: ${formatTeammates(snapshot.onlineNames, Number.POSITIVE_INFINITY)}` : "";
     process.stderr.write(
-      `[prim] \u2713 daemon live \xB7 pid=${snapshot.pid} \xB7 uptime=${Math.round(snapshot.uptimeMs / 1e3)}s \xB7 session=${snapshot.sessionId}
+      `[prim] \u2713 daemon live \xB7 pid=${snapshot.pid} \xB7 uptime=${Math.round(snapshot.uptimeMs / 1e3)}s \xB7 session=${snapshot.sessionId}${team}
 `
     );
   }
@@ -1189,8 +1219,8 @@ async function fetchRecent(args, deps = defaultDeps2) {
   if (args.since !== void 0) {
     params.set("since", args.since);
   }
-  const client = deps.getClient();
   try {
+    const client = deps.getClient();
     const res = await daemonOrDirectGet(
       "decisions_recent",
       `/api/cli/decisions/recent?${params.toString()}`,
@@ -1236,9 +1266,18 @@ function authorLabel(row) {
   }
 }
 var AUTHOR_WIDTH = 18;
+var AREA_WIDTH = 12;
 function padRight(s, width) {
   return s.length >= width ? `${s.slice(0, width - 1)} ` : s.padEnd(width, " ");
 }
+function formatRecentRow(row) {
+  const clock = formatClock(row.classifiedAt);
+  const author = padRight(authorLabel(row), AUTHOR_WIDTH);
+  const areaText = row.area ? `\u2022 ${row.area}` : "\u2022";
+  const areaPlain = padRight(areaText, AREA_WIDTH);
+  const areaCol = row.area ? areaPlain.replace("\u2022", color("\u2022", colorForArea(row.area))) : areaPlain;
+  return `  ${clock}  ${author}${areaCol}${row.intent}`;
+}
 function formatRecentHuman(result) {
   if (result.unavailable !== void 0) {
     return `[prim] recent \xB7 feed not verified \u2014 ${result.unavailable}`;
@@ -1248,12 +1287,7 @@ function formatRecentHuman(result) {
   }
   const lines = [`[prim] recent \xB7 ${String(result.decisions.length)} decision(s)`];
   for (const row of result.decisions) {
-    const clock = formatClock(row.classifiedAt);
-    const author = padRight(authorLabel(row), AUTHOR_WIDTH);
-    const areaText = row.area ? `\u2022 ${row.area}` : "\u2022";
-    const areaPlain = padRight(areaText, 12);
-    const areaCol = row.area ? areaPlain.replace("\u2022", color("\u2022", colorForArea(row.area))) : areaPlain;
-    lines.push(`  ${clock}  ${author}${areaCol}${row.intent}`);
+    lines.push(formatRecentRow(row));
   }
   return lines.join("\n");
 }
@@ -1342,6 +1376,44 @@ function formatConfirmJson(result) {
   return JSON.stringify(result.outcome, null, 2);
 }
 
+// src/decisions/create.ts
+var CREATE_TIMEOUT_MS = 1e4;
+var defaultDeps4 = { getClient };
+function toRequestBody(request) {
+  const candidate = {
+    intent: request.intent,
+    kind: request.kind,
+    rationale: request.rationale,
+    area: request.area,
+    decided: request.decided,
+    alternatives: request.alternatives,
+    confidence: request.confidence,
+    reversibility: request.reversibility,
+    files: request.files
+  };
+  const body = {};
+  for (const [key, value] of Object.entries(candidate)) {
+    const isEmpty = value === void 0 || Array.isArray(value) && value.length === 0;
+    if (!isEmpty) {
+      body[key] = value;
+    }
+  }
+  return body;
+}
+async function fetchCreate(request, deps = defaultDeps4) {
+  const client = deps.getClient();
+  return await client.post("/api/cli/decisions/create", toRequestBody(request), {
+    signal: AbortSignal.timeout(CREATE_TIMEOUT_MS)
+  });
+}
+function formatCreateHuman(outcome) {
+  const id = renderIdentifier({ shortId: outcome.shortId, id: outcome.decisionId });
+  return `[prim] created ${id}.`;
+}
+function formatCreateJson(outcome) {
+  return JSON.stringify(outcome, null, 2);
+}
+
 // src/decisions/show.ts
 var NOT_FOUND_RE3 = /not found/i;
 function colorStatus(status) {
@@ -1354,14 +1426,14 @@ function colorStatus(status) {
   return color(status, "gray");
 }
 var SHOW_TIMEOUT_MS = 1e4;
-var defaultDeps4 = { getClient };
+var defaultDeps5 = { getClient };
 var DecisionNotFoundError = class extends Error {
   constructor(idOrShortId) {
     super(`Decision not found: ${idOrShortId}`);
     this.name = "DecisionNotFoundError";
   }
 };
-async function fetchShow(idOrShortId, deps = defaultDeps4) {
+async function fetchShow(idOrShortId, deps = defaultDeps5) {
   const params = new URLSearchParams({ id: idOrShortId });
   const client = deps.getClient();
   try {
@@ -1478,13 +1550,15 @@ function formatShowJson(result) {
 
 // src/commands/decisions.ts
 var EXIT_NOT_FOUND = 4;
+var EXIT_USAGE = 2;
+var splitList = (value) => (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
 function registerDecisionsCommands(program2) {
   const decisions = program2.command("decisions").description("Inspect the project Decision Graph");
   decisions.command("check").description("Look up active decisions that reference one or more file paths").requiredOption(
     "--files <files>",
     "Comma-separated file paths to check against the Decision Graph"
   ).action(async (opts) => {
-    const filePaths = opts.files.split(",").map((s) => s.trim()).filter(Boolean);
+    const filePaths = splitList(opts.files);
     const result = await checkAffectedDecisions(filePaths);
     const warning = formatDecisionsWarning(result);
     if (warning) {
@@ -1546,10 +1620,44 @@ function registerDecisionsCommands(program2) {
       throw err;
     }
   });
+  decisions.command("create").description("Author a decision directly \u2014 the deliberate manual path around automatic capture").requiredOption("--intent <text>", "What was decided (required)").option("--kind <kind>", "change | exploration | task_execution | unclear (default change)").option("--rationale <text>", "Why the decision was made").option(
+    "--area <area>",
+    "Functional area (auth, data, infra, ui, api, billing, mobile, docs, testing)"
+  ).option("--decided <items>", "Comma-separated option(s) chosen").option("--alternatives <items>", "Comma-separated options considered but rejected").option("--confidence <level>", "high | medium | low (default high)").option("--reversibility <level>", "high | low (default high)").option(
+    "--files <paths>",
+    "Comma-separated repo-relative paths this decision governs (gates edits to them)"
+  ).action(async (opts) => {
+    const request = {
+      intent: opts.intent,
+      kind: opts.kind,
+      rationale: opts.rationale,
+      area: opts.area,
+      decided: splitList(opts.decided),
+      alternatives: splitList(opts.alternatives),
+      confidence: opts.confidence,
+      reversibility: opts.reversibility,
+      files: splitList(opts.files)
+    };
+    try {
+      const outcome = await fetchCreate(request);
+      console.error(formatCreateHuman(outcome));
+      console.log(formatCreateJson(outcome));
+    } catch (err) {
+      if (err instanceof HttpError && err.status >= 400 && err.status < 500) {
+        console.error(`[prim] create rejected: ${err.message}`);
+        console.log(
+          JSON.stringify({ ok: false, status: err.status, error: err.message }, null, 2)
+        );
+        process.exitCode = EXIT_USAGE;
+        return;
+      }
+      throw err;
+    }
+  });
 }
 
 // src/commands/hooks.ts
-import { execSync } from "child_process";
+import { execSync as execSync2 } from "child_process";
 import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
 import { resolve } from "path";
 import { Option } from "commander";
@@ -1587,7 +1695,7 @@ ${hookShim(spec.binName)}
 ${end}`;
 }
 function getGitRoot() {
-  return execSync("git rev-parse --show-toplevel", {
+  return execSync2("git rev-parse --show-toplevel", {
     encoding: "utf-8"
   }).trim();
 }
@@ -1866,7 +1974,7 @@ function registerMovesCommands(program2) {
 
 // src/commands/reconcile.ts
 var EXIT_OK2 = 0;
-var EXIT_USAGE = 2;
+var EXIT_USAGE2 = 2;
 var EXIT_SERVER = 3;
 var HTTP_CLIENT_ERROR_MIN = 400;
 var HTTP_SERVER_ERROR_MIN = 500;
@@ -1910,7 +2018,7 @@ async function performReconcile(idOrShortId, opts = {}) {
       process.stderr.write(`[prim] reconcile rejected: ${err.message}
 `);
       console.log(JSON.stringify({ ok: false, status: err.status, error: err.message }, null, 2));
-      process.exitCode = EXIT_USAGE;
+      process.exitCode = EXIT_USAGE2;
       return;
     }
     const message = err instanceof Error ? err.message : String(err);
@@ -2172,6 +2280,7 @@ import { readFileSync as readFileSync8 } from "fs";
 import { dirname as dirname5, resolve as resolve3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var STATUSLINE_TIMEOUT_MS = 200;
+var STATUSLINE_NAME_CAP = 3;
 function readPackageVersion() {
   try {
     const here = dirname5(fileURLToPath3(import.meta.url));
@@ -2209,7 +2318,14 @@ async function renderStatusline() {
   if (snapshot.presenceStale) {
     return `primitive ${version} (daemon: live \xB7 presence: stale)`;
   }
-  const team = typeof snapshot.onlineCount === "number" ? `team: ${String(snapshot.onlineCount)} online` : "team: \u2014";
+  let team;
+  if (snapshot.onlineNames !== void 0) {
+    team = `team: ${formatTeammates(snapshot.onlineNames, STATUSLINE_NAME_CAP)}`;
+  } else if (typeof snapshot.onlineCount === "number") {
+    team = `team: ${String(snapshot.onlineCount)} online`;
+  } else {
+    team = "team: \u2014";
+  }
   return `primitive ${version} (daemon: live \xB7 ${team})`;
 }
 function registerStatuslineCommands(program2) {
@@ -2222,6 +2338,91 @@ function registerStatuslineCommands(program2) {
   });
 }
 
+// src/commands/welcome.ts
+var CMD_GUTTER = 38;
+var RECENT_LIMIT = 5;
+var REVERSE_PROMPT_LINES = [
+  "What are the most important goals in your organization that you're",
+  "responsible for, right now? What are you not focusing on, in order",
+  "to focus on those goals?"
+];
+var REVERSE_PROMPT = REVERSE_PROMPT_LINES.join(" ");
+function welcomeStateFromRecent(result) {
+  if (result.unavailable !== void 0) {
+    return { org: "unknown" };
+  }
+  if (result.decisions.length === 0) {
+    return { org: "empty" };
+  }
+  return { org: "active", recent: result.decisions.slice(0, RECENT_LIMIT) };
+}
+function formatWelcome(state) {
+  const cmd = (command, desc) => `  ${dim(command.padEnd(CMD_GUTTER))}${desc}`;
+  const bullet = (text) => `  ${color("\u2022", "green")} ${text}`;
+  const head = [
+    bold(color("Welcome to Primitive", "green")),
+    "",
+    "Primitive captures the decisions your team makes while coding into a",
+    "shared graph \u2014 and flags edits that conflict with earlier ones before",
+    "they land.",
+    "",
+    bold("How it works"),
+    bullet("Capture is automatic \u2014 keep coding; your decisions are recorded for you."),
+    bullet("The conflict gate has your back: when an edit conflicts with a"),
+    "    load-bearing decision, prim surfaces it. Run `prim reconcile dec_<id>` to clear",
+    "    that decision and retry.",
+    bullet('Occasional yes/no prompts confirm the "why" behind a decision \u2014'),
+    "    answering keeps the graph trustworthy.",
+    ""
+  ];
+  let body;
+  if (state.org === "active") {
+    body = [
+      bold("Recent team decisions"),
+      ...state.recent.map(formatRecentRow),
+      "",
+      bold("Get started"),
+      cmd("prim decisions check --files <files>", "what governs files you're about to change"),
+      cmd("prim --help", "everything else")
+    ];
+  } else if (state.org === "empty") {
+    body = [
+      bold("Let's seed your decision graph"),
+      "Your team has no decisions recorded yet. Tell me, in your own words:",
+      "",
+      ...REVERSE_PROMPT_LINES.map((line) => `  ${line}`),
+      "",
+      "Share your answer and I'll record each goal as a decision."
+    ];
+  } else {
+    body = [
+      bold("Get started"),
+      cmd("prim decisions recent", "what your team has decided lately"),
+      cmd("prim decisions check --files <files>", "what governs files you're about to change"),
+      cmd("prim --help", "everything else")
+    ];
+  }
+  return [...head, ...body, "", dim("App: https://app.getprimitive.ai")].join("\n");
+}
+function welcomeJson(state) {
+  if (state.org === "active") {
+    return { welcomed: true, org: "active", recent: state.recent };
+  }
+  if (state.org === "empty") {
+    return { welcomed: true, org: "empty", reversePrompt: REVERSE_PROMPT };
+  }
+  return { welcomed: true, org: "unknown" };
+}
+function registerWelcomeCommand(program2, deps = { getClient }) {
+  program2.command("welcome").description("Print a brief orientation to Primitive's decision graph").action(async () => {
+    const result = await fetchRecent({ limit: RECENT_LIMIT }, deps);
+    const state = welcomeStateFromRecent(result);
+    process.stderr.write(`${formatWelcome(state)}
+`);
+    printJson(welcomeJson(state));
+  });
+}
+
 // src/index.ts
 var __dirname2 = dirname6(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(readFileSync9(resolve4(__dirname2, "../package.json"), "utf-8"));
@@ -2242,6 +2443,7 @@ registerCodexCommands(program);
 registerDaemonCommands(program);
 registerReconcileCommands(program);
 registerStatuslineCommands(program);
+registerWelcomeCommand(program);
 process.on("unhandledRejection", (err) => {
   const msg = err instanceof Error ? err.message : String(err);
   console.error(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitive.ai/prim",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "description": "CLI for Primitive's decision graph — passive decision capture, conflict gate, and team presence",
   "type": "module",
   "license": "MIT",