@starlove/orbit 1.4.1 → 2.0.0

package/lib/store/search-words.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How the port reads a search query (`SearchReader.query`), shared so every
+ * adapter reads it the same way. Words are runs of ASCII letters, digits and
+ * `_` holding at least one letter or digit, lowercased; each must start a word
+ * of the document. A query with no words is matched as literal text.
+ */
+/** The query's words, lowercased, in order. */
+export declare function queryWords(query: string): string[];
+/** The text a query with no words is matched by: the query trimmed, or null when blank. */
+export declare function literalQuery(query: string): string | null;

package/lib/store/search-words.js

@@ -0,0 +1,19 @@
+/**
+ * How the port reads a search query (`SearchReader.query`), shared so every
+ * adapter reads it the same way. Words are runs of ASCII letters, digits and
+ * `_` holding at least one letter or digit, lowercased; each must start a word
+ * of the document. A query with no words is matched as literal text.
+ */
+/** The query's words, lowercased, in order. */
+export function queryWords(query) {
+    return query
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, " ")
+        .split(" ")
+        .filter((word) => /[a-z0-9]/.test(word));
+}
+/** The text a query with no words is matched by: the query trimmed, or null when blank. */
+export function literalQuery(query) {
+    const text = query.trim();
+    return text === "" ? null : text;
+}

package/lib/store/types.d.ts

@@ -0,0 +1,452 @@
+/**
+ * Orbit's storage port: everything the core asks of storage, and nothing about
+ * how a database does it. An adapter implements it (SQLite on a computer or
+ * server, IndexedDB in the browser, memory for tests, or yours) and proves
+ * itself with the conformance suite in ./conformance.ts. docs/ARCHITECTURE.md
+ * shows where it sits and how to write one.
+ *
+ * The shape, top down:
+ *
+ *   OrbitStore             one Orbit's data
+ *     .boards              the list of boards (BoardDirectory)
+ *     .board(id)           one board's data (BoardStore)
+ *         .read(r => ...)    a consistent view of what is committed
+ *         .write(w => ...)   one all-or-nothing change, events included
+ *         .watch(listener)   every committed change, from any process or tab
+ *   BlobStore              bytes (images, markdown), apart from records
+ *
+ * What every adapter promises, beyond each method's own words:
+ *
+ * - Records go in and come out as plain data, field for field (the types in
+ *   src/core/model.ts). A record handed out is the caller's copy; changing it
+ *   changes nothing stored, and neither does changing an object after it was
+ *   written.
+ * - Lists come back in the order each method states, so every adapter answers
+ *   alike. "Then by when it was written" means the order the records were
+ *   inserted.
+ * - Failures are OrbitErrors (src/core/errors.ts) with the codes named here.
+ *   A database's own message never reaches an answer: wrap it as
+ *   `storage_failed`, `storage_busy` or `storage_full`, with the original as
+ *   its `cause`.
+ * - Nothing here makes an id or reads a clock. The core gives every id and
+ *   time, so the same input gives the same records on any adapter.
+ */
+import type { Attachment, Board, BoardChange, BoardEntry, Comment, CrossBoardRelation, Id, Label, OrbitEvent, RegisteredBoard, Relation, ReviewVerdict, State, Ticket, TicketLabel, TicketType, Timestamp } from "../core/model.ts";
+export type { BoardChange } from "../core/model.ts";
+/** One Orbit's data: its boards and its settings. */
+export interface OrbitStore {
+    readonly boards: BoardDirectory;
+    /** One board's data. Rejects with `board_not_found` when the directory doesn't list it. */
+    board(id: Id): Promise<BoardStore>;
+    /**
+     * The board holding a lane, card, journal entry or relation with this id,
+     * or null. A `hint` board is looked at first, so the common case costs one
+     * lookup; then board by board in `list()` order.
+     */
+    locate(kind: "state" | "ticket" | "entry" | "relation", id: Id, hint?: Id): Promise<RegisteredBoard | null>;
+    /**
+     * Every cross-board relation, on any board, whose target card is on
+     * `boardId`, with the board it lives on: board by board in `list()` order,
+     * each board's by when each was made, then written. A board that can't be
+     * read now (its file is gone) is skipped, never an error: one board's
+     * trouble must not stop every other board's cards from opening.
+     */
+    relationsInto(boardId: Id): Promise<{
+        board_id: Id;
+        relation: CrossBoardRelation;
+    }[]>;
+    /** Small values this Orbit keeps for itself (the computer's default board). */
+    readonly settings: Settings;
+    /** Point-in-time copies of the data, where the adapter can make them; null where it can't. */
+    readonly backups: Backups | null;
+    /** Lets go of files and connections. The store is unusable afterwards. */
+    close(): Promise<void>;
+}
+/** The list of boards. */
+export interface BoardDirectory {
+    /** Every board, by name in code-point order (as SQLite's default collation), then by when it was registered. */
+    list(): Promise<RegisteredBoard[]>;
+    get(id: Id): Promise<RegisteredBoard | null>;
+    /** The slug as stored: callers normalise it first. */
+    bySlug(slug: string): Promise<RegisteredBoard | null>;
+    /** The board used last (`last_active_at`); among equals, the one registered last. Null when there are none. */
+    latest(): Promise<RegisteredBoard | null>;
+    /**
+     * Makes a board: its storage, its own record (`board`) and whatever `seed`
+     * writes, in its first write; then lists it, with `last_active_at` set to
+     * `board.created_at`. All or nothing: if `seed` throws, no board, no data
+     * and no listing remain, and the error is rethrown. Rejects with
+     * `board_slug_taken` when another board has the slug, checked as one step
+     * with the listing, and with `duplicate_id` when one has the id.
+     */
+    create(board: Board, seed: (w: BoardWriter) => Promise<void>): Promise<RegisteredBoard>;
+    /** Sets `last_active_at` and `updated_at`. Rejects with `board_not_found` for an unknown id. */
+    touch(id: Id, at: Timestamp): Promise<void>;
+    /**
+     * Takes a board off the list and deletes its records, unless `keepData`.
+     * Its blobs are the BlobStore's to remove (`removeBoard`). Returns the
+     * places it deleted, for people to read (files, for SQLite). Rejects with
+     * `board_not_found` for an unknown id.
+     */
+    remove(id: Id, options?: {
+        keepData?: boolean;
+    }): Promise<{
+        removed: string[];
+    }>;
+}
+export interface Settings {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+}
+/** Copies an adapter makes on request: before a destructive change, or after writes. */
+export interface Backups {
+    /**
+     * Copies one board's data as it is committed now, labelled with `reason`.
+     * With `oncePerDay`, nothing is copied when today (UTC) already has one.
+     * Returns where the copy went, or null when none was made.
+     */
+    board(id: Id, reason: string, options?: {
+        oncePerDay?: boolean;
+    }): Promise<string | null>;
+    /** The same for the list of boards and the settings. */
+    directory(reason: string, options?: {
+        oncePerDay?: boolean;
+    }): Promise<string | null>;
+}
+/**
+ * One board's data. Reads and writes go through `read()` and `write()`, so
+ * every adapter answers the same questions about concurrency the same way.
+ */
+export interface BoardStore {
+    readonly id: Id;
+    /**
+     * Runs `body` against what is committed. Everything one read sees is one
+     * committed state: a write that commits while `body` runs shows in full or
+     * not at all, and an open write's changes never show. Resolves with what
+     * `body` returns. A write may wait for reads in progress to finish, so a
+     * read's body must not wait for a write of the same board.
+     */
+    read<T>(body: (r: BoardReader) => Promise<T>): Promise<T>;
+    /**
+     * Runs `body` as one change to the board. Writes to one board run one at a
+     * time across every store over the same data, in this process or another,
+     * so nothing a body reads can change under it until it finishes. Its own
+     * reads see its own changes. If `body` throws, nothing it did remains (no
+     * record, no card number used, no event, no index entry) and the same error
+     * is rethrown. When it returns, its changes commit, its events go to every
+     * watcher, and `write()` resolves with what it returned.
+     *
+     * Never call `read()` or `write()` of the same board inside `body`: the
+     * inner call waits for the outer one, which is waiting for it. Use `w`.
+     * The writer refuses every call (`write_closed`) once `write()` settles.
+     */
+    write<T>(body: (w: BoardWriter) => Promise<T>): Promise<T>;
+    /**
+     * Hears every event the board's writes commit, once, in the order they were
+     * appended: this store's writes and those of any other store over the same
+     * data (another process, another tab). Never an event of a write that
+     * failed. Returns the function that stops listening.
+     */
+    watch(listener: (change: BoardChange) => void): () => void;
+}
+/** What `read()` sees: every kind of record on the board. */
+export interface BoardReader {
+    readonly board: BoardRecordReader;
+    readonly states: StateReader;
+    readonly labels: LabelReader;
+    readonly tickets: TicketReader;
+    readonly ticketLabels: TicketLabelReader;
+    readonly comments: CommentReader;
+    readonly relations: RelationReader;
+    readonly crossBoardRelations: CrossBoardRelationReader;
+    readonly entries: EntryReader;
+    readonly verdicts: VerdictReader;
+    readonly attachments: AttachmentReader;
+    readonly events: EventReader;
+    readonly search: SearchReader;
+}
+/**
+ * What `write()` changes. It reads too, and sees its own changes. Writes
+ * that would break the board's rules of storage are refused with the codes
+ * below, and the refusal throws inside `body`, so the write as a whole fails
+ * unless `body` catches it.
+ *
+ * - A record whose id the board already has: `duplicate_id`.
+ * - A record naming what the board doesn't have: `invalid_reference`. That is
+ *   a `board_id` other than this board's, and a card, lane, label or verdict
+ *   that isn't on the board (a card's lane, a comment's card, a label link's
+ *   card and label, a relation's two cards, an event's or a journal entry's
+ *   card when set, a verdict's earlier verdict when set). Two names are not
+ *   checked: a card's epic (`parent_ticket_id`) and a cross-board relation's
+ *   target.
+ * - Updating or removing a record that isn't there: its kind's not-found
+ *   code (`state_not_found`, `ticket_not_found`, `comment_not_found`,
+ *   `relation_not_found`, `board_entry_not_found`, `attachment_not_found`).
+ */
+export interface BoardWriter extends BoardReader {
+    readonly board: BoardRecordWriter;
+    readonly states: StateWriter;
+    readonly labels: LabelWriter;
+    readonly tickets: TicketWriter;
+    readonly ticketLabels: TicketLabelWriter;
+    readonly comments: CommentWriter;
+    readonly relations: RelationWriter;
+    readonly crossBoardRelations: CrossBoardRelationWriter;
+    readonly entries: EntryWriter;
+    readonly verdicts: VerdictWriter;
+    readonly attachments: AttachmentWriter;
+    readonly events: EventWriter;
+    readonly search: SearchWriter;
+    /** Deletes every record on the board, its own record, events and index included, as a replacing import does first. */
+    clear(): Promise<void>;
+}
+export interface BoardRecordReader {
+    /** Rejects with `board_not_found` only between `clear()` and `set()` inside one write. */
+    get(): Promise<Board>;
+}
+export interface BoardRecordWriter extends BoardRecordReader {
+    /**
+     * Writes the board's own record whole; its id must be this board's
+     * (`invalid_reference`). The directory follows its slug, name, repo_url,
+     * default_branch and updated_at once the write commits. A slug another
+     * board has is refused with `board_slug_taken`.
+     */
+    set(board: Board): Promise<void>;
+    /** Changes the fields given, as `set()` does. */
+    update(patch: BoardPatch): Promise<Board>;
+}
+export type BoardPatch = Partial<Omit<Board, "id" | "created_at">>;
+export interface StateReader {
+    /** By position, then by when each was written. */
+    list(): Promise<State[]>;
+    get(id: Id): Promise<State | null>;
+}
+export interface StateWriter extends StateReader {
+    /** Refuses a name another lane on the board has with `state_name_taken`. */
+    insert(state: State): Promise<void>;
+    /** Refuses as insert() does; `state_not_found` for an unknown id. */
+    update(id: Id, patch: StatePatch): Promise<State>;
+    /** Refuses with `state_has_tickets` while any card, archived or not, is in the lane. */
+    remove(id: Id): Promise<void>;
+}
+export type StatePatch = Partial<Pick<State, "name" | "position" | "is_default" | "role">>;
+export interface LabelReader {
+    /** By name in code-point order. */
+    list(): Promise<Label[]>;
+}
+export interface LabelWriter extends LabelReader {
+    /** Refuses a name another label on the board has with `label_name_taken`. */
+    insert(label: Label): Promise<void>;
+}
+export interface TicketFilter {
+    /** true: archived cards only; false: open cards only; absent: both. */
+    archived?: boolean;
+    /** Only the sub-cards of this epic. */
+    parent?: Id;
+    /** Only the cards in this lane. */
+    state?: Id;
+    /** Only these cards (unknown ids are skipped). */
+    ids?: readonly Id[];
+}
+export interface TicketReader {
+    get(id: Id): Promise<Ticket | null>;
+    byNumber(number: number): Promise<Ticket | null>;
+    /**
+     * The card with this exact title, ignoring the case of ASCII letters (as
+     * SQLite's lower() does): an open card before an archived one, then the
+     * highest number.
+     */
+    byTitle(title: string): Promise<Ticket | null>;
+    /** The cards matching every filter given, by number. */
+    list(filter?: TicketFilter): Promise<Ticket[]>;
+    /** The highest number on the board, archived cards included; 0 when it has none. */
+    lastNumber(): Promise<number>;
+}
+/** A new card: everything but its number, which storage assigns. */
+export type NewTicket = Omit<Ticket, "number">;
+export interface TicketWriter extends TicketReader {
+    /**
+     * Makes a card numbered one more than the highest number on the board now
+     * (archived cards count; the first card is 1), and returns it. Because
+     * writes run one at a time, two callers never get the same number, and a
+     * write that fails uses none.
+     */
+    create(ticket: NewTicket): Promise<Ticket>;
+    /** Writes a card with its number as given (imports). Refuses a number in use with `ticket_number_taken`. */
+    insert(ticket: Ticket): Promise<void>;
+    /** Changes the fields given. Refuses an unknown lane with `invalid_reference`. */
+    update(id: Id, patch: TicketPatch): Promise<Ticket>;
+    /**
+     * Deletes a card and what belongs to it: its comments, label links,
+     * relations either way, cross-board relations from it, review verdicts,
+     * images (records; the bytes are the BlobStore's) and index entry. Events
+     * and journal entries about it stay, their `ticket_id` set to null. Its
+     * sub-cards keep their `parent_ticket_id`.
+     */
+    remove(id: Id): Promise<void>;
+}
+export type TicketPatch = Partial<Omit<Ticket, "id" | "board_id" | "number" | "created_by" | "created_at">>;
+export interface TicketLabelReader {
+    /** The links of these cards (every card's when absent), in the order they were written. */
+    list(ticketIds?: readonly Id[]): Promise<TicketLabel[]>;
+}
+export interface TicketLabelWriter extends TicketLabelReader {
+    /** Replaces the card's labels with these. */
+    set(ticketId: Id, labelIds: readonly Id[]): Promise<void>;
+    /** Adds one; adding a link that exists changes nothing. */
+    add(ticketId: Id, labelId: Id): Promise<void>;
+}
+export interface CommentReader {
+    get(id: Id): Promise<Comment | null>;
+    /** A card's comments (every card's when absent), oldest first, then by when each was written. */
+    list(ticketId?: Id): Promise<Comment[]>;
+    /**
+     * How many comments each card has; cards with none are left out. With
+     * `forAgents`, comments hidden from agents don't count; with `exceptBody`,
+     * neither do comments whose body is exactly that text.
+     */
+    countByTicket(options?: {
+        forAgents?: boolean;
+        exceptBody?: string;
+    }): Promise<{
+        ticket_id: Id;
+        count: number;
+    }[]>;
+}
+export interface CommentWriter extends CommentReader {
+    insert(comment: Comment): Promise<void>;
+    update(id: Id, patch: Pick<Comment, "omitted_for_ai">): Promise<Comment>;
+}
+export interface RelationReader {
+    get(id: Id): Promise<Relation | null>;
+    /** The relations with this card on either side (every relation when absent), by when each was made, then written. */
+    list(ticketId?: Id): Promise<Relation[]>;
+}
+export interface RelationWriter extends RelationReader {
+    /** Refuses a second relation of one type between the same two cards, in the same direction, with `relation_exists`. */
+    insert(relation: Relation): Promise<void>;
+    remove(id: Id): Promise<void>;
+}
+export interface CrossBoardRelationReader {
+    /** The cross-board relations from this card (all of the board's when absent), by when each was made, then written. */
+    list(ticketId?: Id): Promise<CrossBoardRelation[]>;
+}
+export interface CrossBoardRelationWriter extends CrossBoardRelationReader {
+    /** The source card must be on this board; the target is not checked here. Refuses a repeat with `relation_exists`. */
+    insert(relation: CrossBoardRelation): Promise<void>;
+    remove(id: Id): Promise<void>;
+}
+export interface EntryReader {
+    get(id: Id): Promise<BoardEntry | null>;
+    /** Oldest first, then by when each was written. */
+    list(): Promise<BoardEntry[]>;
+}
+export interface EntryWriter extends EntryReader {
+    insert(entry: BoardEntry): Promise<void>;
+    update(id: Id, patch: Partial<Pick<BoardEntry, "struck_at" | "updated_at">>): Promise<BoardEntry>;
+    /** Refuses an id that isn't there with `board_entry_not_found`. */
+    remove(id: Id): Promise<void>;
+}
+export interface VerdictReader {
+    get(id: Id): Promise<ReviewVerdict | null>;
+    /** A card's verdicts (every card's when absent), oldest first, then by when each was written. */
+    list(ticketId?: Id): Promise<ReviewVerdict[]>;
+}
+export interface VerdictWriter extends VerdictReader {
+    insert(verdict: ReviewVerdict): Promise<void>;
+}
+export interface AttachmentReader {
+    get(id: Id): Promise<Attachment | null>;
+    /** A card's images (every card's when absent), oldest first, then by when each was written. */
+    list(ticketId?: Id): Promise<Attachment[]>;
+}
+export interface AttachmentWriter extends AttachmentReader {
+    insert(attachment: Attachment): Promise<void>;
+    remove(id: Id): Promise<void>;
+}
+export interface EventFilter {
+    ticketId?: Id;
+    /** Only events of these types. */
+    types?: readonly string[];
+    /** Only events made at or after this time. */
+    since?: Timestamp;
+}
+export interface EventReader {
+    /** The events matching every filter given, oldest first, then in the order they were appended. */
+    list(filter?: EventFilter): Promise<OrbitEvent[]>;
+    /** For each of these cards, its newest event of these types (oldest-first order's last); cards with none are left out. */
+    latest(ticketIds: readonly Id[], types: readonly string[]): Promise<OrbitEvent[]>;
+    /** Up to `limit` events appended after the event with this id, in the order they were appended; none for an id the board doesn't have. */
+    after(id: Id, limit: number): Promise<OrbitEvent[]>;
+    /** The event appended last, or null. */
+    last(): Promise<OrbitEvent | null>;
+}
+export interface EventWriter extends EventReader {
+    /** Records an event; watchers hear it once the write commits. */
+    append(event: OrbitEvent): Promise<void>;
+}
+/**
+ * What the index holds for one card. The core builds it, so whatever must
+ * never be found (comments hidden from agents) is simply never given.
+ */
+export interface SearchDocument {
+    title: string;
+    description: string;
+    /** Matched by word queries only. */
+    type: TicketType;
+    /** The plan, the summary and the revisions, one per line. */
+    details: string;
+    /** The comments agents may read, one per line. */
+    comments: string;
+}
+export interface SearchHit {
+    ticket_id: Id;
+    /** The adapter's own score; lower is better. */
+    rank: number;
+}
+export interface SearchReader {
+    /**
+     * The open (unarchived) cards whose documents match, best first, at most
+     * `limit`. The query's words are its runs of ASCII letters, digits and `_`
+     * that hold a letter or digit, lowercased (`src/store/search-words.ts`). A
+     * document's words are its runs of letters, digits and `_`, so `snake_case`
+     * is one word. A card matches when, for every query word, its document has
+     * a word starting with it, in any case (an adapter may also fold accents).
+     * A query with no such word matches documents holding the query's text as
+     * it is (trimmed), ignoring the case of ASCII letters; `%`, `_` and `\` in
+     * it are only themselves. A blank query matches nothing.
+     */
+    query(text: string, options: {
+        limit: number;
+    }): Promise<SearchHit[]>;
+}
+export interface SearchWriter extends SearchReader {
+    /** Replaces the card's document. */
+    index(ticketId: Id, document: SearchDocument): Promise<void>;
+    remove(ticketId: Id): Promise<void>;
+}
+/**
+ * Bytes Orbit keeps beside a board's records: images under `attachments/`,
+ * markdown artifacts under `artifacts/`. Paths are POSIX-style and relative
+ * to the board (`attachments/tickets/<card id>/<image id>.png`); one that is
+ * absolute or climbs out with `..` is refused with `invalid_blob_path`.
+ * Blobs aren't part of a board's writes: the core writes the bytes before
+ * the record that names them and removes them after the record is gone, so a
+ * failure leaves an unused blob, never a record without its bytes.
+ */
+export interface BlobStore {
+    /** Stores the bytes, replacing what is there; with `exclusive`, refuses a path in use with `blob_exists`. */
+    put(boardId: Id, path: string, bytes: Uint8Array, options?: {
+        exclusive?: boolean;
+    }): Promise<void>;
+    /** The bytes, or null when nothing is stored at the path. */
+    get(boardId: Id, path: string): Promise<Uint8Array | null>;
+    /** The size in bytes, or null when nothing is stored at the path. */
+    size(boardId: Id, path: string): Promise<number | null>;
+    /** Removing what isn't there changes nothing. */
+    remove(boardId: Id, path: string): Promise<void>;
+    /** Removes every blob of the board. */
+    removeBoard(boardId: Id): Promise<void>;
+    /** Where the bytes are on this machine, for answers that show it; absent where blobs aren't files. */
+    location?(boardId: Id, path: string): string;
+}

package/lib/store/types.js

@@ -0,0 +1,34 @@
+/**
+ * Orbit's storage port: everything the core asks of storage, and nothing about
+ * how a database does it. An adapter implements it (SQLite on a computer or
+ * server, IndexedDB in the browser, memory for tests, or yours) and proves
+ * itself with the conformance suite in ./conformance.ts. docs/ARCHITECTURE.md
+ * shows where it sits and how to write one.
+ *
+ * The shape, top down:
+ *
+ *   OrbitStore             one Orbit's data
+ *     .boards              the list of boards (BoardDirectory)
+ *     .board(id)           one board's data (BoardStore)
+ *         .read(r => ...)    a consistent view of what is committed
+ *         .write(w => ...)   one all-or-nothing change, events included
+ *         .watch(listener)   every committed change, from any process or tab
+ *   BlobStore              bytes (images, markdown), apart from records
+ *
+ * What every adapter promises, beyond each method's own words:
+ *
+ * - Records go in and come out as plain data, field for field (the types in
+ *   src/core/model.ts). A record handed out is the caller's copy; changing it
+ *   changes nothing stored, and neither does changing an object after it was
+ *   written.
+ * - Lists come back in the order each method states, so every adapter answers
+ *   alike. "Then by when it was written" means the order the records were
+ *   inserted.
+ * - Failures are OrbitErrors (src/core/errors.ts) with the codes named here.
+ *   A database's own message never reaches an answer: wrap it as
+ *   `storage_failed`, `storage_busy` or `storage_full`, with the original as
+ *   its `cause`.
+ * - Nothing here makes an id or reads a clock. The core gives every id and
+ *   time, so the same input gives the same records on any adapter.
+ */
+export {};

package/llms.txt

@@ -0,0 +1,63 @@
+# Starscape Orbit
+
+> Orbit is a local-first kanban board that AI agents use for project management: tasks, tickets, plans, decisions, and lessons. The human watches the work move on a calm, live board. It's free and open source (AGPL-3.0), published on npm as `@starlove/orbit`, and needs Node.js 22.16+ (or 24).
+
+If your user said something like "install and use Starscape Orbit", this page is for you, the agent. Follow the setup below, then use Orbit for this user's project tracking from now on.
+
+## Set it up
+
+1. **Check Node.js.** `node -v` must print 22.16 or newer (24 is best; 23 won't do). If it doesn't, ask the user before installing or upgrading Node.
+2. **Install Orbit.** Run `npm install -g @starlove/orbit` (skip if `orbit --version` already prints 2 or later). Orbit keeps every board in its data folder, `~/.starscape/orbit`. If the user had Orbit 1.x (boards in `~/.orbit`), Orbit says their old boards are waiting: run `orbit migrate`, which copies them over and only reads the old folder.
+3. **Connect yourself to Orbit's MCP server.** It's a stdio server started with `orbit mcp`. Use the entry for your harness:
+   - Claude Code: `claude mcp add --scope user orbit -- orbit mcp`
+   - Codex CLI: `codex mcp add orbit -- orbit mcp`
+   - Hermes Agent, in `~/.hermes/config.yaml`:
+     ```yaml
+     mcp_servers:
+       orbit:
+         command: orbit
+         args: [mcp]
+     ```
+   - Cursor (`~/.cursor/mcp.json`), Claude Desktop (`claude_desktop_config.json`), Gemini CLI (`~/.gemini/settings.json`), and most other clients:
+     ```json
+     { "mcpServers": { "orbit": { "command": "orbit", "args": ["mcp"] } } }
+     ```
+   - VS Code's GitHub Copilot and Copilot CLI share `~/.copilot/mcp-config.json`: `{ "mcpServers": { "orbit": { "type": "stdio", "command": "orbit", "args": ["mcp"], "tools": ["*"] } } }`
+
+   Add `-e ORBIT_AGENT_NAME=<your name>` (or an `env` entry) so the board shows who did what.
+
+   Desktop apps often can't see the shell's PATH. If `orbit` isn't found, use absolute paths: set the command to the output of `command -v node`, and set the args to `["<output of npm root -g>/@starlove/orbit/lib/cli/orbit.js", "mcp"]`. Most clients load MCP servers at startup, so tell the user if they need to restart the app or open a new session.
+4. **Start the board app** so the user can see it. If `curl -s http://127.0.0.1:13701/api/health` fails, run `orbit run -d`, which starts Orbit in the background. Give the user the URL, normally http://localhost:13701.
+5. **Create a board for the project.** Send `boards` (orbit_read) to see what exists. If no board fits, send `boards new <project name>` (orbit_write). From a shell it's `orbit boards` and `orbit boards new <name>`.
+6. **Remember it.** Save a durable note wherever you keep standing instructions (your memory, `AGENTS.md`, `CLAUDE.md`, rules files): *"Use Starscape Orbit for project management: tasks, tickets, kanban, plans, decisions. Board: `<slug>`. Start with `orbit view <slug>` (or orbit_read `view <slug>`); `help` lists the commands."* So every agent in a repo lands on its board, run `orbit boards link <slug>` in the repo and commit the `orbit.json` it writes (one line: `{ "board": "<slug>" }`); commands that name no board then use it. Otherwise, with several boards, name the board in each command (`view <slug>`, `<slug>#12`, `--board <slug>`), or make it the default for every folder on this computer with `orbit boards use <slug>`. Ask before editing files other people share.
+7. **Tell the user it's ready.** Give them the board URL and the board name, and explain how to hand you work: "Move a card to AI Ready, or say 'work on ticket 12'."
+
+## Run it on a server
+
+Orbit has no login yet, so keep it on a private network.
+
+- On the server: `npm install -g @starlove/orbit && DATA_DIR=/var/lib/orbit orbit run -d`. For restarts after a reboot, run it under systemd, or build the `Dockerfile` that ships with Orbit and run the container with a restart policy.
+- Reach it privately with `tailscale serve --bg 13701` (only your tailnet can reach it) or an SSH tunnel: `ssh -N -L 13701:127.0.0.1:13701 user@server`.
+- To connect an agent on another machine, use remote mode: the same MCP entry, plus the environment variables `ORBIT_MODE=remote`, `ORBIT_API_URL=<private URL>`, and optionally `ORBIT_BOARD=<slug>`. For example:
+  `claude mcp add orbit --scope user -e ORBIT_MODE=remote -e ORBIT_API_URL=https://orbit.your-tailnet.ts.net -e ORBIT_AGENT_NAME=claude -- orbit mcp`
+- The `orbit` CLI takes the same variables, and every Orbit serves its own `/llms.txt` with the commands for that version.
+- Never put Orbit on a public address.
+
+## Day to day
+
+Orbit speaks one small command language. Over MCP you get two tools, orbit_read and orbit_write, each taking one command line, with long text in `text`. In a shell the same commands are `orbit view`, `orbit take`, `orbit finish 12 -m "..."`. Cards are #n (in a shell write `orbit card 12`, because a word starting with `#` is a comment), lanes are named, priorities are words. AI Ready holds cards an agent may take: each says its goal and when it's done. The core loop:
+
+1. `view` shows the board, one line per card.
+2. `take` claims the next card in AI Ready, or `take #12` the card the user names. It returns the card with the board's rules and next steps.
+3. If the goal or "done" is unclear, `ask #12` with what's missing, then stop.
+4. `finish #12` with what changed and how you checked it. The card moves to Review for the human.
+
+When the user mentions new work, `new <title>` makes a card instead of a private list. `help` lists every command; the guide linked below has the whole workflow. Never edit Orbit's SQLite files directly.
+
+## Links
+
+- [Agent guide](https://orbit.starscape.app/guide.md): the full workflow, every command, and the HTTP API
+- [README](https://orbit.starscape.app/README.md): install, storage, backups, and self-hosting
+- [npm package](https://www.npmjs.com/package/@starlove/orbit)
+- [Source](https://github.com/brucestarlove/ss-orbit)
+- [Live demo](https://orbit.starscape.app/app/): runs in the browser only, so agents can't connect to it