sfora-cli 0.11.0 → 0.12.1

package/README.md

@@ -328,6 +328,41 @@ silent would look connected and be deaf.
 
 Warnings (reconnects) go to stderr, so `--json` stdout stays parseable.
 
+## Where — who's in which document
+
+`sfora watch` tells you when a document moves. `sfora where` tells you where
+people *are* — the reverse of the presence roster, and the answer to "the doc
+I'm looking at" when nobody sent a link.
+
+```bash
+$ sfora where
+Thijs is editing test-document.md — https://www.sfora.ai/org/acme/notes/k17e8c0...
+Dogfood Bot is editing test-document.md (block k7f3a2cx) — https://www.sfora.ai/org/acme/notes/k17e8c0...
+
+$ sfora where Thijs
+Thijs is editing test-document.md — https://www.sfora.ai/org/acme/notes/k17e8c0...
+
+$ sfora where --json | jq -r 'select(.type == "human") | .path'
+```
+
+* The name is optional and takes a member name, an id, or `self`. A name nobody
+  in the workspace answers to is an error, not an empty list — "who?" and
+  "nowhere" are different answers.
+* The block id appears only when somebody claimed one. Agents address blocks
+  natively; humans are present at document level today.
+* **Asking declares nothing.** Unlike `watch` and every write, `where` is a
+  plain `GET` — running it never puts you in a document.
+* You see what your key can open, and nothing else: presence carries a title
+  and a link, so a document you're not on the project for never appears.
+* `--as <agent>` composes — the answer is then that agent's view.
+* `--json` writes **NDJSON**, one record per person-in-a-document (flat, so
+  each line stands alone): `memberId`, `name`, `type`, `kind`, `block`,
+  `lastSeenAt`, `ttlSeconds`, `docId`, `title`, `filename`, `path`, `project`,
+  `url`.
+
+An entry is live while `lastSeenAt` is inside `ttlSeconds` (90) — the server
+filters on it before answering, so nothing stale comes back.
+
 ## Links — `sfora url` · `sfora open`
 
 Every workspace thing has a page. The server says where; the CLI prints it.

package/dist/api-client.d.ts

@@ -193,6 +193,80 @@ export interface DocPresence {
     blockResolved: boolean | null;
     here: DocPresenceMember[];
 }
+/** One occupant of a document, as `GET /v1/presence` reports them. */
+export interface PresenceOccupant {
+    memberId: string;
+    name: string;
+    type: "human" | "agent";
+    kind: "viewing" | "editing";
+    /** The block they have claimed, or `null` for the document at large. */
+    block: string | null;
+    lastSeenAt: number;
+}
+/** One document somebody is in, with everyone who is in it. */
+export interface PresenceDocument {
+    docId: string;
+    title: string;
+    filename: string;
+    /** The fs path — what `sfora cat` and `sfora put` take. */
+    path: string;
+    project: {
+        slug: string;
+        name: string;
+    };
+    url: string;
+    here: PresenceOccupant[];
+}
+/**
+ * `GET /v1/presence` — where everybody is, grouped by document.
+ *
+ * `ttlSeconds` is the server's own definition of "still here": an entry is
+ * live while `Date.now() - lastSeenAt` is inside it. Stated rather than
+ * assumed, so a consumer never has to hardcode the heartbeat window.
+ */
+export interface PresenceView {
+    ttlSeconds: number;
+    /** The member asked about, when one was named; `null` for everybody. */
+    member: {
+        memberId: string;
+        name: string;
+        type: "human" | "agent";
+    } | null;
+    documents: PresenceDocument[];
+}
+/**
+ * One room, as `GET /api/rooms` lists it. `joined: false` rows appear only
+ * with `?all=1` — open rooms the caller can discover and self-join.
+ */
+export interface Room {
+    _id: string;
+    name: string;
+    type: string;
+    description?: string | null;
+    /** The owning project's id (not slug), or null for a free-standing room. */
+    projectId: string | null;
+    joined: boolean;
+}
+/** Who wrote a chat message. Humans and agents are the same member model. */
+export interface ChatAuthor {
+    _id: string;
+    name: string;
+    type: "human" | "agent";
+}
+/** One message, as a row of `GET /api/rooms/:id/messages`. Body is markdown. */
+export interface ChatMessage {
+    _id: string;
+    body: string;
+    _creationTime: number;
+    /** Null when the author's member row is gone. */
+    author: ChatAuthor | null;
+}
+/** A page of messages, NEWEST FIRST — the server paginates backwards. */
+export interface MessagesPage {
+    page: ChatMessage[];
+    continueCursor: string;
+    isDone: boolean;
+}
 /**
  * One event off `/v1/events`.
  *
@@ -449,6 +523,17 @@ export declare class SforaApiClient {
         block?: string;
         leave?: boolean;
     }): Promise<DocPresence | null>;
+    /**
+     * `GET /v1/presence` — where everybody is right now.
+     *
+     * The reverse of {@link declarePresence}, and a pure read: asking never
+     * enrols the asker in anything. `member` takes an id, a name, or `self`.
+     *
+     * Documents the key cannot open are absent from the answer — the server
+     * filters, the CLI prints. That is why this returns everything it is given
+     * rather than filtering again here.
+     */
+    listPresence(member?: string): Promise<PresenceView>;
     /**
      * `GET /v1/events` — the long-poll. Blocks server-side until something
      * happens or the wait budget elapses, then answers with a cursor to poll
@@ -475,6 +560,34 @@ export declare class SforaApiClient {
      * projection is the server saying which row these bytes are.
      */
     resolveDocId(fsPath: string): Promise<string | null>;
+    /**
+     * `GET /api/rooms` — the caller's rooms. `all` adds open-but-unjoined rooms
+     * (`joined: false`), so the room can be found before it is joined.
+     */
+    listRooms(all?: boolean): Promise<Room[]>;
+    /** `POST /api/rooms/:id/join` — self-join an open room. Idempotent. */
+    joinRoom(roomId: string): Promise<{
+        joined: boolean;
+        already: boolean;
+    }>;
+    /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
+    listRoomMessages(roomId: string, limit?: number): Promise<MessagesPage>;
+    /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
+    sendRoomMessage(roomId: string, body: string): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
+     *
+     * `client` is a short slug ("cli", "claude-code") that names what kind of
+     * client is on the line; the app reads it out next to the online dot. The
+     * server sanitizes and owns the field on every beat, so a beat without a
+     * label also clears a stale one.
+     */
+    heartbeat(params?: {
+        roomId?: string;
+        client?: string;
+    }): Promise<void>;
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     readInbox(): Promise<string>;
     /** `GET /v1/fs/me/api-key` — text identity (no key material). */

package/dist/api-client.js

@@ -141,13 +141,15 @@ export class SforaApiClient {
      * where "stop" has to mean the socket and not just a flag the caller will
      * read after it returns.
      */
-    signal) {
+    signal, 
+    /** The fs surface speaks markdown; the /api chat endpoints speak JSON. */
+    contentType = "text/markdown") {
         const headers = Object.create(null);
         headers.Authorization = `Bearer ${this.#apiKey}`;
         if (this.#actAs)
             headers["X-Sfora-Act-As"] = this.#actAs;
         if (body !== undefined)
-            headers["Content-Type"] = "text/markdown";
+            headers["Content-Type"] = contentType;
         let res;
         try {
             res = await fetch(`${this.#baseUrl}${path}`, {
@@ -562,6 +564,20 @@ export class SforaApiClient {
             throw error;
         }
     }
+    /**
+     * `GET /v1/presence` — where everybody is right now.
+     *
+     * The reverse of {@link declarePresence}, and a pure read: asking never
+     * enrols the asker in anything. `member` takes an id, a name, or `self`.
+     *
+     * Documents the key cannot open are absent from the answer — the server
+     * filters, the CLI prints. That is why this returns everything it is given
+     * rather than filtering again here.
+     */
+    async listPresence(member) {
+        const query = member ? `?member=${encodeURIComponent(member)}` : "";
+        return this.#json(`/v1/presence${query}`);
+    }
     /**
      * `GET /v1/events` — the long-poll. Blocks server-side until something
      * happens or the wait budget elapses, then answers with a cursor to poll
@@ -597,6 +613,41 @@ export class SforaApiClient {
         const view = await this.readBlocks(fsPath);
         return view.document?.id ?? null;
     }
+    // ─── Chat (rooms + messages) ─────────────────────────────────────
+    /**
+     * `GET /api/rooms` — the caller's rooms. `all` adds open-but-unjoined rooms
+     * (`joined: false`), so the room can be found before it is joined.
+     */
+    async listRooms(all = false) {
+        return this.#json(`/api/rooms${all ? "?all=1" : ""}`);
+    }
+    /** `POST /api/rooms/:id/join` — self-join an open room. Idempotent. */
+    async joinRoom(roomId) {
+        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/join`);
+        return this.#jsonFrom(res);
+    }
+    /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
+    async listRoomMessages(roomId, limit = 30) {
+        return this.#json(`/api/rooms/${encodeURIComponent(roomId)}/messages?limit=${limit}`);
+    }
+    /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
+    async sendRoomMessage(roomId, body) {
+        // Through #request like every other call, so network failures surface as
+        // SforaApiError(0, "network_error") and `--as` rides the shared headers.
+        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body }), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
+    /**
+     * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
+     *
+     * `client` is a short slug ("cli", "claude-code") that names what kind of
+     * client is on the line; the app reads it out next to the online dot. The
+     * server sanitizes and owns the field on every beat, so a beat without a
+     * label also clears a stale one.
+     */
+    async heartbeat(params = {}) {
+        await this.#request("POST", "/api/presence", JSON.stringify(params), undefined, "application/json");
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/chat.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `sfora rooms` / `sfora join` / `sfora chat` — the room in the terminal.
+ *
+ * Humans and agents are the same member model in the same rooms, and this is
+ * how either sits in the conversation from a terminal. Everything
+ * decision-shaped lives here as pure functions (name resolution, message
+ * formatting, the tail loop) so it can be tested with canned data; `cli.ts`
+ * owns the process — readline, signals, the real streams.
+ *
+ * The live tail rides `/v1/events`, the same long-poll `sfora watch` uses: the
+ * feed carries a `message` event for every room the caller is in (never their
+ * own posts), so a new message is a wake, not a poll schedule. The event's
+ * preview is clipped server-side at 280 chars, so the loop treats it as a
+ * DOORBELL only — on any message event for this room it refetches the recent
+ * page and prints what it has not printed yet, deduped by message id. That is
+ * also what makes the caller's own sends (echoed by the send itself) never
+ * print twice.
+ */
+import type { AgentEventsPage, ChatMessage, Room } from "./api-client.js";
+/**
+ * A presence client label as the server stores it: lowercase, `[a-z0-9-]`
+ * only, at most 32 chars. Anything that sanitizes to nothing is nothing —
+ * the caller falls through to its next guess.
+ */
+export declare function sanitizeClientSlug(raw: string | undefined): string | undefined;
+/**
+ * What kind of client is on the line, for the presence label.
+ *
+ * Order: an explicit `--client` flag wins; then `AI_AGENT` (the part before
+ * the first underscore — `claude-code_2-1-233_agent` names "claude-code");
+ * then `CLAUDE_CODE_ENTRYPOINT` being set at all means Claude Code is
+ * driving; else this is a plain terminal — "cli". Env is passed in, not
+ * read, so every rung is testable.
+ */
+export declare function detectClient(env: Record<string, string | undefined>, flag?: string): string;
+/** How `sfora rooms` and `sfora join` spell a room name as an argument. */
+export declare function roomSlug(name: string): string;
+export type RoomMatch = {
+    kind: "match";
+    room: Room;
+} | {
+    kind: "ambiguous";
+    candidates: Room[];
+} | {
+    kind: "none";
+};
+/**
+ * The room a reference names: exact name or slug first (case-insensitive),
+ * then an unambiguous prefix of either. Ambiguity is reported, not guessed —
+ * sending a message into the wrong room is the failure this exists to prevent.
+ * A joined room beats an unjoined one on an otherwise-tied exact match.
+ */
+export declare function resolveRoomRef(rooms: Room[], ref: string): RoomMatch;
+/** House rule: a displayed name leads with a capital, wherever it renders. */
+export declare function capitalizeName(name: string): string;
+/**
+ * A chat timestamp, relative — a room is read as a conversation, and "3m ago"
+ * is how a conversation tells time. Beyond a week the date says it better.
+ */
+export declare function relativeTime(ts: number, now: number): string;
+/**
+ * A message body for a terminal: markdown, lightly dressed. Headings read
+ * bold, fence delimiters and blockquote markers go dim; everything else is
+ * printed as the author wrote it — the CLI prints what the server sends, and
+ * markdown is already a terminal-legible format.
+ */
+export declare function renderChatBody(markdown: string): string;
+/**
+ * One message: `Author  3m ago`, then the body indented under it. The author
+ * is bold because it is the line's anchor; the time is dim because it is
+ * context, not content.
+ */
+export declare function renderChatMessage(msg: ChatMessage, now: number): string;
+/** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
+export declare function renderRoomList(rooms: Room[]): string;
+/** Everything the tail loop needs from the outside world. */
+export interface ChatTailDeps {
+    /** One `/v1/events` long-poll. Rejects on a drop — the loop backs off. */
+    poll(since: number): Promise<AgentEventsPage>;
+    /** The room's recent page, any order — refetched when the doorbell rings. */
+    fetchRecent(): Promise<ChatMessage[]>;
+    /** Print one message the reader has not seen. */
+    print(message: ChatMessage): void;
+    /** A warning, never mixed into the transcript. */
+    warn(text: string): void;
+    sleep(ms: number): Promise<void>;
+}
+export interface ChatTailOptions {
+    roomId: string;
+    /** Message ids already on screen — history, and the caller's own sends. */
+    seen: Set<string>;
+    /** Events cursor to start from (the CLI starts at "now"). */
+    since: number;
+    stopped?: () => boolean;
+    backoffMs?: number;
+}
+/**
+ * Poll until stopped, printing new messages in this room as they arrive.
+ *
+ * The same three rules `watchLoop` holds, held here for the same reasons: the
+ * cursor survives reconnects and only moves forward, drops back off (doubling
+ * to {@link MAX_BACKOFF_MS}) and recover fast, and nothing prints twice — the
+ * `seen` set is the single ledger, shared with the prompt's own sends.
+ */
+export declare function chatTailLoop(deps: ChatTailDeps, options: ChatTailOptions): Promise<number>;

package/dist/chat.js

@@ -0,0 +1,221 @@
+/**
+ * `sfora rooms` / `sfora join` / `sfora chat` — the room in the terminal.
+ *
+ * Humans and agents are the same member model in the same rooms, and this is
+ * how either sits in the conversation from a terminal. Everything
+ * decision-shaped lives here as pure functions (name resolution, message
+ * formatting, the tail loop) so it can be tested with canned data; `cli.ts`
+ * owns the process — readline, signals, the real streams.
+ *
+ * The live tail rides `/v1/events`, the same long-poll `sfora watch` uses: the
+ * feed carries a `message` event for every room the caller is in (never their
+ * own posts), so a new message is a wake, not a poll schedule. The event's
+ * preview is clipped server-side at 280 chars, so the loop treats it as a
+ * DOORBELL only — on any message event for this room it refetches the recent
+ * page and prints what it has not printed yet, deduped by message id. That is
+ * also what makes the caller's own sends (echoed by the send itself) never
+ * print twice.
+ */
+import { colors } from "./render.js";
+import { MAX_BACKOFF_MS } from "./watch.js";
+const dim = (text) => `${colors.dim}${text}${colors.reset}`;
+// ─── Client identity (presence label) ────────────────────────────────
+/**
+ * A presence client label as the server stores it: lowercase, `[a-z0-9-]`
+ * only, at most 32 chars. Anything that sanitizes to nothing is nothing —
+ * the caller falls through to its next guess.
+ */
+export function sanitizeClientSlug(raw) {
+    if (!raw)
+        return undefined;
+    const slug = raw.toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 32);
+    return slug || undefined;
+}
+/**
+ * What kind of client is on the line, for the presence label.
+ *
+ * Order: an explicit `--client` flag wins; then `AI_AGENT` (the part before
+ * the first underscore — `claude-code_2-1-233_agent` names "claude-code");
+ * then `CLAUDE_CODE_ENTRYPOINT` being set at all means Claude Code is
+ * driving; else this is a plain terminal — "cli". Env is passed in, not
+ * read, so every rung is testable.
+ */
+export function detectClient(env, flag) {
+    const fromFlag = sanitizeClientSlug(flag);
+    if (fromFlag)
+        return fromFlag;
+    const fromAgent = sanitizeClientSlug(env.AI_AGENT?.split("_")[0]);
+    if (fromAgent)
+        return fromAgent;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined)
+        return "claude-code";
+    return "cli";
+}
+// ─── Room resolution ─────────────────────────────────────────────────
+/** How `sfora rooms` and `sfora join` spell a room name as an argument. */
+export function roomSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * The room a reference names: exact name or slug first (case-insensitive),
+ * then an unambiguous prefix of either. Ambiguity is reported, not guessed —
+ * sending a message into the wrong room is the failure this exists to prevent.
+ * A joined room beats an unjoined one on an otherwise-tied exact match.
+ */
+export function resolveRoomRef(rooms, ref) {
+    const want = ref.trim().toLowerCase().replace(/^#/, "");
+    if (!want)
+        return { kind: "none" };
+    const bySlug = roomSlug(want);
+    const exact = rooms.filter((r) => r.name.toLowerCase() === want || roomSlug(r.name) === bySlug);
+    if (exact.length === 1)
+        return { kind: "match", room: exact[0] };
+    if (exact.length > 1) {
+        const joined = exact.filter((r) => r.joined);
+        if (joined.length === 1)
+            return { kind: "match", room: joined[0] };
+        return { kind: "ambiguous", candidates: exact };
+    }
+    const prefix = rooms.filter((r) => r.name.toLowerCase().startsWith(want) ||
+        roomSlug(r.name).startsWith(bySlug));
+    if (prefix.length === 1)
+        return { kind: "match", room: prefix[0] };
+    if (prefix.length > 1)
+        return { kind: "ambiguous", candidates: prefix };
+    return { kind: "none" };
+}
+// ─── Message formatting ──────────────────────────────────────────────
+/** House rule: a displayed name leads with a capital, wherever it renders. */
+export function capitalizeName(name) {
+    return name ? name.charAt(0).toUpperCase() + name.slice(1) : name;
+}
+/**
+ * A chat timestamp, relative — a room is read as a conversation, and "3m ago"
+ * is how a conversation tells time. Beyond a week the date says it better.
+ */
+export function relativeTime(ts, now) {
+    const diff = Math.max(0, now - ts);
+    const minutes = Math.floor(diff / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 7)
+        return `${days}d ago`;
+    // The reader's LOCAL date — toISOString would name yesterday for an
+    // evening timestamp anywhere east of UTC.
+    const d = new Date(ts);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/**
+ * A message body for a terminal: markdown, lightly dressed. Headings read
+ * bold, fence delimiters and blockquote markers go dim; everything else is
+ * printed as the author wrote it — the CLI prints what the server sends, and
+ * markdown is already a terminal-legible format.
+ */
+export function renderChatBody(markdown) {
+    let inFence = false;
+    return markdown
+        .replace(/\s+$/, "")
+        .split("\n")
+        .map((line) => {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            return `  ${dim(line)}`;
+        }
+        if (inFence)
+            return `  ${line}`;
+        if (/^#{1,6}\s/.test(line)) {
+            return `  ${colors.bold}${line}${colors.reset}`;
+        }
+        if (/^\s*>/.test(line))
+            return `  ${dim(line)}`;
+        return `  ${line}`;
+    })
+        .join("\n");
+}
+/**
+ * One message: `Author  3m ago`, then the body indented under it. The author
+ * is bold because it is the line's anchor; the time is dim because it is
+ * context, not content.
+ */
+export function renderChatMessage(msg, now) {
+    const author = capitalizeName(msg.author?.name ?? "Unknown");
+    const header = `${colors.bold}${author}${colors.reset}  ${dim(relativeTime(msg._creationTime, now))}`;
+    return `${header}\n${renderChatBody(msg.body)}`;
+}
+/** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
+export function renderRoomList(rooms) {
+    if (rooms.length === 0)
+        return dim("(no rooms)");
+    const width = Math.max(...rooms.map((r) => r.name.length));
+    return rooms
+        .map((room) => {
+        const marker = room.joined
+            ? `${colors.green}●${colors.reset}`
+            : dim("○");
+        const meta = room.joined
+            ? dim(room.type)
+            : dim(`${room.type} · not joined — sfora join ${roomSlug(room.name)}`);
+        return `  ${marker} ${room.name.padEnd(width)}  ${meta}`;
+    })
+        .join("\n");
+}
+/**
+ * Poll until stopped, printing new messages in this room as they arrive.
+ *
+ * The same three rules `watchLoop` holds, held here for the same reasons: the
+ * cursor survives reconnects and only moves forward, drops back off (doubling
+ * to {@link MAX_BACKOFF_MS}) and recover fast, and nothing prints twice — the
+ * `seen` set is the single ledger, shared with the prompt's own sends.
+ */
+export async function chatTailLoop(deps, options) {
+    const stopped = options.stopped ?? (() => false);
+    const firstBackoff = options.backoffMs ?? 1_000;
+    let cursor = options.since;
+    let backoff = firstBackoff;
+    while (!stopped()) {
+        let page;
+        try {
+            page = await deps.poll(cursor);
+        }
+        catch (error) {
+            if (stopped())
+                break;
+            const message = error instanceof Error ? error.message : String(error);
+            deps.warn(`reconnecting in ${Math.round(backoff / 1000)}s — ${message}`);
+            await deps.sleep(backoff);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+            continue;
+        }
+        backoff = firstBackoff;
+        const rang = page.events.some((e) => e.type === "message" && e.roomId === options.roomId);
+        if (rang) {
+            try {
+                const recent = await deps.fetchRecent();
+                const fresh = recent
+                    .filter((m) => !options.seen.has(m._id))
+                    .sort((a, b) => a._creationTime - b._creationTime);
+                for (const msg of fresh) {
+                    options.seen.add(msg._id);
+                    deps.print(msg);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                deps.warn(`could not fetch new messages — ${message}`);
+            }
+        }
+        // Never backwards: an empty page holds the cursor where it was.
+        cursor = Math.max(cursor, page.cursor);
+    }
+    return cursor;
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The CLI's argument grammar, as a pure function.
+ *
+ * Lifted out of `cli.ts` so it can be tested: importing `cli.ts` runs
+ * `main()`, which is exactly what a test must not do. Nothing here reads the
+ * process — argv in, a parsed shape out.
+ */
+export interface CliArgs {
+    command?: string;
+    rest: string[];
+    org?: string;
+    cwd: string;
+    mcp: boolean;
+    help: boolean;
+    url?: string;
+    key?: string;
+    bot?: string;
+    as?: string;
+    web?: string;
+    project?: string;
+    column?: string;
+    draft: boolean;
+    json: boolean;
+    local: boolean;
+    cloud: boolean;
+    block?: string;
+    self: boolean;
+    wait?: number;
+    message?: string;
+    limit?: number;
+    client?: string;
+}
+export declare function parseArgs(argv: string[]): CliArgs;

package/dist/cli-args.js

@@ -0,0 +1,92 @@
+/**
+ * The CLI's argument grammar, as a pure function.
+ *
+ * Lifted out of `cli.ts` so it can be tested: importing `cli.ts` runs
+ * `main()`, which is exactly what a test must not do. Nothing here reads the
+ * process — argv in, a parsed shape out.
+ */
+export function parseArgs(argv) {
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--mcp")
+            args.mcp = true;
+        else if (a === "--help" || a === "-h")
+            args.help = true;
+        else if (a === "--org")
+            args.org = argv[++i];
+        else if (a.startsWith("--org="))
+            args.org = a.slice("--org=".length);
+        else if (a === "--cwd")
+            args.cwd = argv[++i] ?? "/";
+        else if (a.startsWith("--cwd="))
+            args.cwd = a.slice("--cwd=".length);
+        else if (a === "--url")
+            args.url = argv[++i];
+        else if (a.startsWith("--url="))
+            args.url = a.slice("--url=".length);
+        else if (a === "--key")
+            args.key = argv[++i];
+        else if (a.startsWith("--key="))
+            args.key = a.slice("--key=".length);
+        else if (a === "--bot" || a === "--agent")
+            args.bot = argv[++i];
+        else if (a.startsWith("--bot="))
+            args.bot = a.slice("--bot=".length);
+        else if (a.startsWith("--agent="))
+            args.bot = a.slice("--agent=".length);
+        else if (a === "--as")
+            args.as = argv[++i];
+        else if (a.startsWith("--as="))
+            args.as = a.slice("--as=".length);
+        else if (a === "--web")
+            args.web = argv[++i];
+        else if (a.startsWith("--web="))
+            args.web = a.slice("--web=".length);
+        else if (a === "--project")
+            args.project = argv[++i];
+        else if (a.startsWith("--project="))
+            args.project = a.slice("--project=".length);
+        else if (a === "--column")
+            args.column = argv[++i];
+        else if (a.startsWith("--column="))
+            args.column = a.slice("--column=".length);
+        else if (a === "--draft")
+            args.draft = true;
+        else if (a === "--json")
+            args.json = true;
+        else if (a === "--local")
+            args.local = true;
+        else if (a === "--cloud")
+            args.cloud = true;
+        else if (a === "--block")
+            args.block = argv[++i];
+        else if (a.startsWith("--block="))
+            args.block = a.slice("--block=".length);
+        else if (a === "--self")
+            args.self = true;
+        else if (a === "--wait")
+            args.wait = Number.parseInt(argv[++i] ?? "", 10);
+        else if (a.startsWith("--wait="))
+            args.wait = Number.parseInt(a.slice("--wait=".length), 10);
+        else if (a === "-m" || a === "--message")
+            args.message = argv[++i];
+        else if (a.startsWith("--message="))
+            args.message = a.slice("--message=".length);
+        else if (a === "-n" || a === "--limit")
+            args.limit = Number.parseInt(argv[++i] ?? "", 10);
+        else if (a.startsWith("--limit="))
+            args.limit = Number.parseInt(a.slice("--limit=".length), 10);
+        else if (a === "--client")
+            args.client = argv[++i];
+        else if (a.startsWith("--client="))
+            args.client = a.slice("--client=".length);
+        else if (!a.startsWith("-")) {
+            if (!args.command)
+                args.command = a;
+            else
+                args.rest.push(a);
+        }
+    }
+    return args;
+}

package/dist/cli.js

@@ -14,84 +14,13 @@ import { taskUploadFilename } from "./format/taskUploadFilename.js";
 import { createSforaShell, createLocalShell, } from "./index.js";
 import { openerCommand } from "./opener.js";
 import { blocksCommand, presenceNotice, putCommand, } from "./block-commands.js";
-import { colors, renderWriteEffect, urlLine, PRESENCE_NOTE } from "./render.js";
+import { colors, ndjson, presenceRecords, renderPresence, renderWriteEffect, urlLine, PRESENCE_NOTE, } from "./render.js";
 import { parseWatchTarget, watchLoop } from "./watch.js";
 import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, } from "./local/workspace.js";
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
-function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--mcp")
-            args.mcp = true;
-        else if (a === "--help" || a === "-h")
-            args.help = true;
-        else if (a === "--org")
-            args.org = argv[++i];
-        else if (a.startsWith("--org="))
-            args.org = a.slice("--org=".length);
-        else if (a === "--cwd")
-            args.cwd = argv[++i] ?? "/";
-        else if (a.startsWith("--cwd="))
-            args.cwd = a.slice("--cwd=".length);
-        else if (a === "--url")
-            args.url = argv[++i];
-        else if (a.startsWith("--url="))
-            args.url = a.slice("--url=".length);
-        else if (a === "--key")
-            args.key = argv[++i];
-        else if (a.startsWith("--key="))
-            args.key = a.slice("--key=".length);
-        else if (a === "--bot" || a === "--agent")
-            args.bot = argv[++i];
-        else if (a.startsWith("--bot="))
-            args.bot = a.slice("--bot=".length);
-        else if (a.startsWith("--agent="))
-            args.bot = a.slice("--agent=".length);
-        else if (a === "--as")
-            args.as = argv[++i];
-        else if (a.startsWith("--as="))
-            args.as = a.slice("--as=".length);
-        else if (a === "--web")
-            args.web = argv[++i];
-        else if (a.startsWith("--web="))
-            args.web = a.slice("--web=".length);
-        else if (a === "--project")
-            args.project = argv[++i];
-        else if (a.startsWith("--project="))
-            args.project = a.slice("--project=".length);
-        else if (a === "--column")
-            args.column = argv[++i];
-        else if (a.startsWith("--column="))
-            args.column = a.slice("--column=".length);
-        else if (a === "--draft")
-            args.draft = true;
-        else if (a === "--json")
-            args.json = true;
-        else if (a === "--local")
-            args.local = true;
-        else if (a === "--cloud")
-            args.cloud = true;
-        else if (a === "--block")
-            args.block = argv[++i];
-        else if (a.startsWith("--block="))
-            args.block = a.slice("--block=".length);
-        else if (a === "--self")
-            args.self = true;
-        else if (a === "--wait")
-            args.wait = Number.parseInt(argv[++i] ?? "", 10);
-        else if (a.startsWith("--wait="))
-            args.wait = Number.parseInt(a.slice("--wait=".length), 10);
-        else if (!a.startsWith("-")) {
-            if (!args.command)
-                args.command = a;
-            else
-                args.rest.push(a);
-        }
-    }
-    return args;
-}
+import { parseArgs } from "./cli-args.js";
+import { chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -132,15 +61,29 @@ Browse & read:
   Add --json to any list command (projects/posts/tasks/ls/me) for
   machine-readable output and stable scripting.
 
+Chat:
+  sfora rooms                         List rooms (● joined · ○ open to join)
+  sfora join <room>                   Join an open room
+  sfora chat <room> [-n <count>]      Read the room, then type to talk —
+                                      new messages stream in live
+  sfora chat <room> -m "text"         Send one message and exit (for scripts
+                                      and agents)
+
+  Chat shows others what's on the line: the CLI reports itself in presence,
+  and a coding agent is named automatically (Claude Code sets its own
+  environment). Add --client <name> to say it yourself.
+
 Write, and watch others write:
   sfora blocks <path>                 List a document's addressable blocks
   sfora put <path> <file.md>          Write a file (add --block <id> for one block)
   sfora put <path> --block <id> -     …or pipe the block's markdown on stdin
   sfora watch <path-or-project>       Stream write pings (add --json for NDJSON)
+  sfora where [name]                  Who's in which document right now
 
   Every write prints what it did — "changed" (with how many block ids
   survived) or "no change". Watching and writing make you visible in the
-  document; watch --self also shows your own writes.
+  document; watch --self also shows your own writes. "where" is a read only —
+  asking never puts you in a document.
 
 Agents & config:
   sfora --mcp [--org <slug>]          Run as an MCP server (for agents)
@@ -408,6 +351,7 @@ const VERBS = new Set([
     "blocks",
     "put",
     "watch",
+    "where",
     "post",
     "task",
     "doc",
@@ -419,6 +363,9 @@ const VERBS = new Set([
     "whoami",
     "comment",
     "react",
+    "rooms",
+    "join",
+    "chat",
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
@@ -528,6 +475,59 @@ async function runVerb(args, fs, client) {
         }
         return runWatch(args, client, args.rest[0]);
     }
+    // `where` — the reverse of presence. Card #345.
+    //
+    // Nothing is declared by running it: the server answers a query and the CLI
+    // prints it. That matters enough to be a property of the verb rather than a
+    // note about it — `sfora where` is the command an agent runs to find out
+    // where a human is working, and a version of it that joined the roster would
+    // make an agent appear in a document it had only asked about.
+    //
+    // The name is the whole argument list. `--as` composes for free (it is a
+    // header on the client, so `sfora where --as bot` asks as the bot and gets
+    // the bot's visibility), and no `--project` filter exists because the answer
+    // is already scoped to what this key can open.
+    if (args.command === "where") {
+        const view = await client.listPresence(args.rest[0]);
+        if (args.json) {
+            // NDJSON, matching `watch --json`: one record per line, no wrapper. A
+            // pretty-printed object would break `sfora where --json | jq -r .url`
+            // for the same reason it would there.
+            for (const record of presenceRecords(view)) {
+                process.stdout.write(`${ndjson(record)}\n`);
+            }
+            return;
+        }
+        console.log(renderPresence(view));
+        return;
+    }
+    // Chat — the same rooms the app shows, from the terminal. Humans and agents
+    // are the same member model, so this is how either sits in the conversation.
+    if (args.command === "rooms") {
+        const rooms = await client.listRooms(true);
+        if (args.json)
+            return emitJson(rooms);
+        console.log(renderRoomList(rooms));
+        return;
+    }
+    if (args.command === "join") {
+        if (!args.rest[0])
+            throw new Error("usage: sfora join <room>");
+        const room = await resolveRoomOrThrow(client, args.rest[0]);
+        const result = await client.joinRoom(room._id);
+        if (args.json)
+            return emitJson({ ...result, roomId: room._id, name: room.name });
+        ok(result.already
+            ? `Already in #${roomSlug(room.name)}`
+            : `Joined #${roomSlug(room.name)}`);
+        return;
+    }
+    if (args.command === "chat") {
+        if (!args.rest[0]) {
+            throw new Error('usage: sfora chat <room> [-n <count>] [-m "text"]');
+        }
+        return runChat(args, client);
+    }
     if (args.command === "me" || args.command === "whoami") {
         const text = (await client.readMe()).trim();
         if (args.json) {
@@ -757,6 +757,179 @@ async function runWatch(args, client, target) {
         process.off("SIGTERM", onSignal);
     }
 }
+/**
+ * The room a reference names, or a thrown explanation.
+ *
+ * Resolution reads `?all=1` so an unjoined room can still be found — `sfora
+ * join dogfood` has to work before the caller is in it. Ambiguity throws with
+ * the candidates rather than guessing: sending into the wrong room is the
+ * failure worth a retype.
+ */
+async function resolveRoomOrThrow(client, ref) {
+    const rooms = await client.listRooms(true);
+    const match = resolveRoomRef(rooms, ref);
+    if (match.kind === "match")
+        return match.room;
+    if (match.kind === "ambiguous") {
+        throw new Error(`'${ref}' matches several rooms — say which:\n` +
+            match.candidates.map((r) => `  ${roomSlug(r.name)}`).join("\n"));
+    }
+    throw new Error(`no room matches '${ref}' — run \`sfora rooms\` to see them`);
+}
+/**
+ * `sfora chat <room>` — the room in the terminal, wired to the real process.
+ *
+ * Everything decision-shaped (name resolution, formatting, the tail loop)
+ * lives in `chat.ts` where it is tested; this owns readline, ^C, and the two
+ * modes: `-m` sends one message and exits (what scripts and agents use), bare
+ * `chat` prints history and opens a prompt with a live tail above it.
+ */
+async function runChat(args, client) {
+    const room = await resolveRoomOrThrow(client, args.rest[0]);
+    const tag = `#${roomSlug(room.name)}`;
+    const isTty = Boolean(process.stdin.isTTY);
+    if (!room.joined) {
+        // Offered inline on a terminal; stated as the fix everywhere else — a
+        // script cannot answer a question, so it gets the command instead.
+        if (args.message !== undefined || !isTty) {
+            throw new Error(`you have not joined ${tag} — run \`sfora join ${roomSlug(room.name)}\` first`);
+        }
+        const ask = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const answer = await new Promise((res) => ask.question(`You have not joined ${tag} — join? (y/n) `, res));
+        ask.close();
+        if (!/^y(es)?$/i.test(answer.trim()))
+            return;
+        await client.joinRoom(room._id);
+        console.log(`${colors.green}✓${colors.reset} Joined ${tag}`);
+    }
+    // Presence is decoration: a beat that fails changes nothing about the
+    // conversation, so every beat here is best-effort and silent. The label
+    // says WHAT is on the line — "cli", or "claude-code" when a coding agent
+    // is driving — so the app can show the terminal next to the online dot.
+    const clientLabel = detectClient(process.env, args.client);
+    const beat = () => client.heartbeat({ roomId: room._id, client: clientLabel }).catch(() => { });
+    // One-shot send.
+    if (args.message !== undefined) {
+        const text = args.message.trim();
+        if (!text)
+            throw new Error('usage: sfora chat <room> -m "text"');
+        // One beat alongside the send — a script that speaks was here, briefly.
+        void beat();
+        const { messageId } = await client.sendRoomMessage(room._id, text);
+        if (args.json) {
+            console.log(JSON.stringify({ messageId, roomId: room._id }, null, 2));
+            return;
+        }
+        console.log(`${colors.green}✓${colors.reset} Sent to ${tag}`);
+        return;
+    }
+    // History, oldest first — the page arrives newest-first.
+    const limit = Number.isFinite(args.limit) && args.limit > 0
+        ? Math.min(args.limit, 100)
+        : 30;
+    // Seed the seen set from as many messages as the tail's refetch pulls (20):
+    // with -n below that, the doorbell would otherwise "discover" older history
+    // and flood it as if it had just arrived. Print only the asked-for n.
+    const history = await client.listRoomMessages(room._id, Math.max(limit, 20));
+    const seeded = history.page.slice().reverse();
+    const seen = new Set(seeded.map((m) => m._id));
+    const messages = seeded.slice(-limit);
+    if (messages.length === 0) {
+        console.log(`${colors.dim}(no messages yet)${colors.reset}`);
+    }
+    for (const msg of messages)
+        console.log(renderChatMessage(msg, Date.now()));
+    process.stderr.write(`${colors.dim}${tag} — type to send · /quit (or ^C) to leave${colors.reset}\n`);
+    // Sitting in the room is being present in it: beat now, then every ~45s
+    // (presence expires server-side, so the cadence just has to outrun the
+    // timeout). `unref` so the timer never keeps the process alive on its own.
+    void beat();
+    const pulse = setInterval(() => void beat(), 45_000);
+    pulse.unref?.();
+    // The prompt and the tail share one screen: an arriving message clears the
+    // prompt line, prints, and readline redraws the prompt with whatever was
+    // being typed. `readline.clearLine` over anything fancier — robust beats
+    // pretty at 80 columns.
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: isTty,
+    });
+    rl.setPrompt(`${colors.cyan}${tag}${colors.reset} `);
+    const printAbove = (text) => {
+        if (isTty) {
+            readline.clearLine(process.stdout, 0);
+            readline.cursorTo(process.stdout, 0);
+        }
+        process.stdout.write(`${text}\n`);
+        if (isTty)
+            rl.prompt(true);
+    };
+    // ^C has to reach the socket, same as `watch`: the long-poll hangs for tens
+    // of seconds, and a flag alone would leave a terminal that says it stopped
+    // and hasn't. Closing readline ends the line iterator; aborting the request
+    // ends the poll; the loop sees `stopped()` and returns.
+    let stop = false;
+    const inFlight = new AbortController();
+    rl.on("SIGINT", () => rl.close());
+    rl.on("close", () => {
+        stop = true;
+        inFlight.abort();
+    });
+    const wait = Number.isFinite(args.wait) ? args.wait : undefined;
+    const tail = chatTailLoop({
+        poll: (since) => client.pollEvents({ since, wait, signal: inFlight.signal }),
+        fetchRecent: async () => (await client.listRoomMessages(room._id, 20)).page,
+        print: (msg) => printAbove(renderChatMessage(msg, Date.now())),
+        warn: (text) => printAbove(`${colors.dim}${text}${colors.reset}`),
+        sleep,
+    }, {
+        roomId: room._id,
+        seen,
+        // Cursor on SERVER time: the newest history message's _creationTime.
+        // A client clock running fast would otherwise open a blind window at
+        // startup; any overlap re-delivery is absorbed by the seen set.
+        since: history.page[0]?._creationTime ?? Date.now(),
+        stopped: () => stop,
+    });
+    if (isTty)
+        rl.prompt();
+    for await (const input of rl) {
+        const line = input.trim();
+        if (!line) {
+            if (isTty)
+                rl.prompt();
+            continue;
+        }
+        if (line === "/quit" || line === "/exit" || line === "/q")
+            break;
+        try {
+            // The send's own echo is the typed line still on screen; recording the
+            // id keeps the tail's refetch from printing it a second time.
+            const { messageId } = await client.sendRoomMessage(room._id, line);
+            seen.add(messageId);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`${colors.red}error:${colors.reset} ${msg}\n`);
+        }
+        if (isTty)
+            rl.prompt();
+    }
+    stop = true;
+    inFlight.abort();
+    rl.close();
+    clearInterval(pulse);
+    // A parting beat, best-effort — awaited so quitting doesn't race process
+    // exit, but never allowed to hold the door.
+    await beat();
+    await tail.catch(() => { });
+    if (isTty)
+        console.log("");
+}
 /**
  * A shared command's result, on the real streams.
  *

package/dist/render.d.ts

@@ -10,7 +10,7 @@
  * SERVER SENDS. Nothing here computes a URL, a route, or a block id — each
  * comes off a response and is formatted.
  */
-import type { BlockConflict, BlockView, BlocksView, WriteEffect } from "./api-client.js";
+import type { BlockConflict, BlockView, BlocksView, PresenceView, WriteEffect } from "./api-client.js";
 export declare const colors: {
     reset: string;
     bold: string;
@@ -89,6 +89,36 @@ export declare function renderWriteEffect(effect: WriteEffect | null): string |
  * noise and the second one teaches nothing.
  */
 export declare const PRESENCE_NOTE = "you are visible as editing this document";
+/**
+ * `sfora where` — one sentence per person, and a link they can be met at.
+ *
+ * A SENTENCE, not a table. The answer to "where is Thijs" is read once and
+ * acted on immediately ("open that document"), so it is written the way it
+ * would be said: *Thijs is editing test-document.md — <url>*. A columnar
+ * listing would be denser and would make the reader assemble the sentence
+ * themselves.
+ *
+ * The block id rides in parentheses only when somebody claimed one. Humans
+ * are present at document level today (the editor has no cheap source-offset
+ * mapping), so an always-present column would be empty on most rows and read
+ * as a fault rather than as an absence of claim.
+ *
+ * Grouped runs, no headers: two people in one document print as two adjacent
+ * lines naming the same file. The repetition is the grouping, and it costs
+ * nothing to scan — where a header would cost a line per document and break
+ * `sfora where | grep` into a two-line lookup.
+ */
+export declare function renderPresence(view: PresenceView): string;
+/**
+ * `sfora where --json` — one flat record per person-in-a-document, per line.
+ *
+ * FLAT, where the wire shape is grouped. NDJSON's contract is that a line is a
+ * record, and the record a consumer of this wants is "who is where": grouping
+ * would make a line's shape depend on how many people happened to be in one
+ * file, and `jq -r .url` would stop working. The document's fields are copied
+ * onto each line rather than referenced, so no line needs another to be read.
+ */
+export declare function presenceRecords(view: PresenceView): unknown[];
 /** One `doc.write` / `doc.delete` ping from `/v1/events`, as one line. */
 export interface DocPing {
     type: "doc.write" | "doc.delete";

package/dist/render.js

@@ -163,6 +163,78 @@ export function renderWriteEffect(effect) {
  * noise and the second one teaches nothing.
  */
 export const PRESENCE_NOTE = "you are visible as editing this document";
+/**
+ * `sfora where` — one sentence per person, and a link they can be met at.
+ *
+ * A SENTENCE, not a table. The answer to "where is Thijs" is read once and
+ * acted on immediately ("open that document"), so it is written the way it
+ * would be said: *Thijs is editing test-document.md — <url>*. A columnar
+ * listing would be denser and would make the reader assemble the sentence
+ * themselves.
+ *
+ * The block id rides in parentheses only when somebody claimed one. Humans
+ * are present at document level today (the editor has no cheap source-offset
+ * mapping), so an always-present column would be empty on most rows and read
+ * as a fault rather than as an absence of claim.
+ *
+ * Grouped runs, no headers: two people in one document print as two adjacent
+ * lines naming the same file. The repetition is the grouping, and it costs
+ * nothing to scan — where a header would cost a line per document and break
+ * `sfora where | grep` into a two-line lookup.
+ */
+export function renderPresence(view) {
+    const lines = [];
+    const totalHere = view.documents.reduce((n, d) => n + d.here.length, 0);
+    if (totalHere === 0) {
+        return dim(view.member
+            ? `${view.member.name} isn't in a document right now`
+            : "nobody is in a document right now");
+    }
+    for (const doc of view.documents) {
+        for (const who of doc.here) {
+            lines.push(presenceLine(doc, who));
+        }
+    }
+    return lines.join("\n");
+}
+function presenceLine(doc, who) {
+    const where = who.block
+        ? `${doc.filename} ${dim(`(block ${who.block})`)}`
+        : doc.filename;
+    return `${who.name} is ${who.kind} ${where} ${dim("—")} ${urlLine(doc.url)}`;
+}
+/**
+ * `sfora where --json` — one flat record per person-in-a-document, per line.
+ *
+ * FLAT, where the wire shape is grouped. NDJSON's contract is that a line is a
+ * record, and the record a consumer of this wants is "who is where": grouping
+ * would make a line's shape depend on how many people happened to be in one
+ * file, and `jq -r .url` would stop working. The document's fields are copied
+ * onto each line rather than referenced, so no line needs another to be read.
+ */
+export function presenceRecords(view) {
+    const records = [];
+    for (const doc of view.documents) {
+        for (const who of doc.here) {
+            records.push({
+                memberId: who.memberId,
+                name: who.name,
+                type: who.type,
+                kind: who.kind,
+                block: who.block,
+                lastSeenAt: who.lastSeenAt,
+                ttlSeconds: view.ttlSeconds,
+                docId: doc.docId,
+                title: doc.title,
+                filename: doc.filename,
+                path: doc.path,
+                project: doc.project.slug,
+                url: doc.url,
+            });
+        }
+    }
+    return records;
+}
 /** `HH:MM:SS` in the reader's own timezone — a ping is read as it lands. */
 export function pingTime(ts) {
     return new Date(ts).toTimeString().slice(0, 8);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [