sfora-cli 0.14.0 → 0.16.0

package/README.md

@@ -399,3 +399,131 @@ print nothing, and `sfora url` on one says so.
 Reads outside `projects/<slug>/(posts|drafts)`, `inbox/mentions.md`, and
 `me/api-key` return `ENOENT`; writes outside the post/draft dirs return `EACCES`.
 ```
+
+## macOS and shared local operations
+
+The desktop app and npm CLI use the same Node-only `sfora-cli/local-core`
+operations. `sfora desktop path/to/file.md` opens a local file in the installed
+Sfora macOS app. `sfora open` continues to open Sfora web URLs. npm installation
+still requires Node 22.13+; the desktop distribution bundles its own CLI runtime.
+Both read the existing `~/.sfora/config.json` profiles. Config writes are atomic
+and process-locked; no account is required for local files or local skill scans.
+
+Local Markdown snapshots contain the canonical `path`, unmodified UTF-8
+`content`, and SHA-256 `revision`. Saving requires the loaded revision; Save As
+refuses existing destinations. BOM and line endings are preserved. A stale
+revision reports a conflict instead of overwriting an external edit. Locks
+coordinate Sfora processes; other editors do not participate in those locks.
+A crashed process may leave a `.sfora-lock` directory: the error identifies it
+for removal after confirming no process is using it.
+
+## Project skills
+
+Skills are complete recursive bundles: `SKILL.md`, scripts, references, and
+binary assets retain exact bytes and executable flags. Import/install never
+executes skill scripts. Symbolic links, traversal, duplicate case-insensitive
+paths, invalid hashes and oversized bundles are rejected (1,000 files,
+5 MiB/file, 20 MiB total).
+
+```sh
+sfora skills scan ~/.agents/skills ~/.codex/skills --json
+sfora skills list --project my-project
+sfora skills push ./my-skill --project my-project --expected-version 0
+sfora skills pull my-skill ./my-skill.bundle.json --project my-project
+sfora skills install my-skill --project my-project --skills-target ~/.agents/skills
+sfora skills diff ~/.agents/skills/my-skill my-skill --project my-project
+sfora skills uninstall ~/.agents/skills/my-skill
+```
+
+Push uses an explicit base version (`0` creates a skill); updating an existing
+skill also requires its `--expected-revision` draft token from `skills list`.
+Saving the draft and publishing are separately checked operations, so a
+concurrent change cannot silently publish somebody else's draft. Use
+`--version N` to pull/install a particular immutable release. Offline bundle
+installation is `skills install-file bundle.json --skills-target <directory>`.
+
+Install targets are explicit. A sibling `.name.sfora-install.json` records
+ownership and last installed hash. Existing unowned folders are never replaced;
+updates and uninstalls refuse locally modified installations. Save or push
+those modifications before retrying. `skills pull` writes a new bundle JSON
+file and refuses to overwrite an existing file.
+
+Cloud document callers can use `SforaApiClient.readPathSnapshot()` and pass its
+revision to `writePath(..., { expectedRevision })`. CLI writes accept
+`put <path> <file.md> --expected-revision N`. A null read revision means the
+server did not advertise concurrency support; clients must not infer a token.
+
+Published Skills are also mounted read-only in the ordinary filesystem view:
+
+```sh
+sfora ls /projects/my-project/skills
+sfora ls /projects/my-project/skills/my-skill/scripts
+sfora cat /projects/my-project/skills/my-skill/SKILL.md
+```
+
+Nested directories, binary reads and executable metadata are preserved. Draft
+changes appear here only after publication; use `skills push` or the project
+workbench to change a bundle. Cloud installations record both the immutable
+bundle hash and numeric `sourceVersion`; resolving “latest” pins that version
+before downloading so concurrent publications cannot mix provenance and bytes.
+
+
+### Persistent local skill inventory
+
+Requires Node 22.13 or later. Desktop and CLI share a private SQLite catalogue at `~/.sfora/skills/catalog.sqlite`. Skill names and content hashes are not identity; separate local copies remain separate until explicitly linked.
+
+```sh
+sfora skills roots add ~/.my-skills "My skills"
+sfora skills roots add-project ~/Developer/my-project "My project"
+sfora skills roots --json
+sfora skills inventory --json
+sfora skills roots remove <root-id>
+```
+
+Registered roots and local identities survive restart. Removing a root only removes tracking. Missing or inaccessible skills retain last-known metadata and an unavailable state. `skills scan --json` retains its array result; `skills inventory --json` includes scan warnings. SQLite handles concurrent clients and transaction rollback. Do not edit or delete the catalogue to rebuild observations. Explicit cloud bindings and read-only transfer previews share this catalogue. Transfer execution and recovery remain separate mission increments.
+
+
+### Explicit cloud bindings and transfer previews
+
+```sh
+sfora skills bind <location-id> <cloud-name> --project my-project
+sfora skills bindings --json
+sfora skills status <binding-id> --json
+sfora skills plan <binding-id> push --json
+sfora skills plan <binding-id> pull --json
+sfora skills relocate <location-id> /new/skill-folder
+```
+
+Take the location ID from `skills inventory`. Linking verifies the authenticated member, deployment, organization, project and cloud skill ID. Names are lookup hints. A same-name replacement cannot silently take over a binding. Relocation preserves identity after an explicitly chosen folder move; register the destination discovery root first.
+
+Explicit adoption of equal, verified published and local content establishes a baseline. Differing content starts with an unknown baseline, or preserves an existing confirmed baseline. Status compares fresh local bytes and a pinned published cloud revision against that baseline. It distinguishes synchronized, local changed, remote changed, conflict, missing and unavailable content. An unavailable cloud request exits with an error and never reports synchronization.
+
+Plans contain exact IDs, local and remote hashes, published version, draft revision and per-file byte/mode metadata. They perform no writes. Unknown baselines, conflicts, existing cloud drafts and unverified local ownership block automatic replacement. CLI previews verify ownership against both the installation receipt and the current filesystem object. A replaced link, file or locally edited copy is never treated as an unchanged managed directory. Reviewed pushes can be executed through the journal below. Recovery for local pull/install mutations and migration of the older transfer commands remain tracked by #470 and #472.
+
+The first write upgrades catalogue schema 1 to 2 transactionally after making a private SQLite-consistent `.v1-<id>.sqlite` backup beside the catalogue. Read-only inspection can read schema 1 without upgrading it. Older clients fail closed after an upgrade; update the desktop app and CLI together. Keep the backup until the updated clients have been verified.
+
+
+### Guarded pushes and recovery
+
+```sh
+sfora skills plan <binding-id> push --json > push-plan.json
+sfora skills queue push-plan.json
+sfora skills apply <operation-id>
+sfora skills operations --json
+sfora skills recover <operation-id>
+sfora skills cancel <unstarted-operation-id>
+sfora skills plan-install <cloud-name> --project my-project --skills-target /existing/parent
+```
+
+`apply push-plan.json` queues and starts a push in one command. A reviewed plan is rechecked against current local content, the explicit binding, published version and draft revision. The server must advertise identity-checked writes; the client refuses to apply against an older server. Existing cloud drafts and changed review tokens stop the operation.
+
+The private `~/.sfora/skills/operations.sqlite` journal commits intent before requests and reserves the qualified cloud target across upload/publication. A live worker cannot be recovered by another process. Recover an interrupted worker's operation before starting another operation on its target. Lost responses produce a durable `needs-attention` outcome. Recovery checks whether the exact intended next draft or publication landed before retrying, and a separate confirmation receipt covers interruption during the local baseline commit. Completed operations are not republished. Cancelling is supported only before work starts; it does not pretend to undo remote effects.
+
+`plan-install` produces a read-only preview for a new, empty destination and blocks occupied destinations. Pull and installation previews can be queued and applied through the same journal. Local updates preserve the previous directory in an operation-specific backup; recovery verifies ownership and staged content before continuing, and preserves external edits. Backups and staged snapshots remain available for inspection. An interruption between creating a destination and recording its owner requires inspection rather than guessing ownership. The older `push`, `pull` and `install` commands retain their existing behavior; use `plan`/`apply` for binding-aware update safety. Use `skills apply-batch ids.json` or `skills recover-batch ids.json` with a JSON array of operation IDs. Outcomes are retained per item and completed work is not replayed. Ctrl-C stops after the current item and cancels unstarted items. In the macOS app, Skills → Transfers reviews the same device-wide queue before running or recovering selected plans.
+
+The desktop keeps a cached local skill inventory and watches registered/agent folders. Known file changes re-read only affected skills; new paths and periodic reconciliation repair missed events. Refresh requests a full reconciliation. Removed or inaccessible folders keep their stable identity and last known metadata. Watchers are hints, not authority for transfer planning, which always rechecks current files.
+
+
+In the macOS app, **On this Mac → Push to Sfora / Update local copy** opens a project chooser and a **Review changes** dialog. Published cloud skills offer **Install on this Mac**, followed by the native destination picker and the same review. No CLI plan file is needed. Opening a review creates no binding or queued operation; confirmation rechecks current content and records the durable transfer. Matching unlinked copies can be explicitly linked. Different unlinked copies remain blocked rather than receiving an invented baseline.
+
+A first publication continues into the existing project draft editor. After successful publication, the original local copy is linked only if its files still match the published version. A failed link does not turn a successful publication into a failed result. Transfers remains the history/recovery view, including work queued from the CLI.

package/dist/SforaFs.js

@@ -76,6 +76,8 @@ function classify(path) {
         if (seg.length === 2)
             return { kind: "projectDir", slug };
         const dir = seg[2];
+        if (dir === "skills")
+            return { kind: "skillPath", slug, name: seg[3], path: seg.slice(4).join("/") };
         if (dir === "links.md" && seg.length === 3) {
             return { kind: "linksFile", slug };
         }
@@ -560,7 +562,20 @@ export class SforaFs {
                 throw enoent("open", normalize(path));
         }
     }
+    async #skillManifest(slug, name) {
+        const manifest = await this.#client.readSkillManifest(slug, name);
+        const paths = new Set();
+        for (const file of manifest.files) {
+            const parts = file.path.split("/");
+            for (let count = 1; count <= parts.length; count++)
+                paths.add(parts.slice(0, count).join("/"));
+        }
+        this.#entrySnapshots.set(`/projects/${slug}/skills/${name}`, [...paths]);
+        return manifest;
+    }
     async readFile(path, options) {
+        if (classify(path).kind === "skillPath")
+            return Buffer.from(await this.readFileBuffer(path)).toString(toNodeEncoding(readEncoding(options)));
         const text = await this.#readText(path);
         const enc = readEncoding(options);
         if (enc === "utf8" || enc === "utf-8")
@@ -568,12 +583,25 @@ export class SforaFs {
         return Buffer.from(text, "utf8").toString(toNodeEncoding(enc));
     }
     async readFileBuffer(path) {
+        const loc = classify(path);
+        if (loc.kind === "skillPath") {
+            if ((await this.stat(path)).isDirectory)
+                throw eisdir("read", normalize(path));
+            try {
+                return await this.#client.readSkillFile(loc.slug, loc.name, loc.path);
+            }
+            catch (error) {
+                throw fromApi(error, "open", normalize(path));
+            }
+        }
         const text = await this.#readText(path);
         return new TextEncoder().encode(text);
     }
     async writeFile(path, content, _options) {
         const loc = classify(path);
         const norm = normalize(path);
+        if (loc.kind === "skillPath")
+            throw eacces("open", norm);
         if (loc.kind === "inboxFile" || loc.kind === "meFile") {
             throw eacces("open", norm);
         }
@@ -746,6 +774,21 @@ export class SforaFs {
         const norm = normalize(path);
         try {
             switch (loc.kind) {
+                case "skillPath": {
+                    if (!loc.name) {
+                        await this.#client.listSkillDirectories(loc.slug);
+                        return this.#dirStat();
+                    }
+                    const manifest = await this.#skillManifest(loc.slug, loc.name);
+                    if (!loc.path)
+                        return this.#dirStat();
+                    const file = manifest.files.find(file => file.path === loc.path);
+                    if (file)
+                        return { ...this.#fileStat(new Date(0), file.size), mode: file.executable ? 0o755 : FILE_MODE };
+                    if (manifest.files.some(file => file.path.startsWith(`${loc.path}/`)))
+                        return this.#dirStat();
+                    throw enoent("stat", norm);
+                }
                 case "root":
                 case "projectsDir":
                 case "inboxDir":
@@ -853,6 +896,27 @@ export class SforaFs {
         });
         try {
             switch (loc.kind) {
+                case "skillPath": {
+                    if (!loc.name) {
+                        const directories = (await this.#client.listSkillDirectories(loc.slug)).directories;
+                        this.#entrySnapshots.set(`/projects/${loc.slug}/skills`, directories.map(skill => skill.name));
+                        return directories.map(skill => dirent(skill.name, true));
+                    }
+                    const manifest = await this.#skillManifest(loc.slug, loc.name);
+                    if (manifest.files.some(file => file.path === loc.path))
+                        throw enotdir("scandir", norm);
+                    const prefix = loc.path ? `${loc.path}/` : "";
+                    const children = new Map();
+                    for (const file of manifest.files) {
+                        if (!file.path.startsWith(prefix))
+                            continue;
+                        const parts = file.path.slice(prefix.length).split("/");
+                        children.set(parts[0], parts.length > 1);
+                    }
+                    if (loc.path && !children.size)
+                        throw enoent("scandir", norm);
+                    return [...children].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, directory]) => dirent(name, directory));
+                }
                 case "root":
                     return [
                         dirent("inbox", true),
@@ -884,6 +948,7 @@ export class SforaFs {
                         dirent("map.md", false),
                         dirent("posts", true),
                         dirent("pulls", true),
+                        dirent("skills", true),
                     ];
                     // `public/` only appears once the board is shared publicly.
                     if ((await this.#publicSlug(loc.slug)) != null) {
@@ -998,6 +1063,7 @@ export class SforaFs {
         const loc = classify(path);
         const norm = normalize(path);
         switch (loc.kind) {
+            case "skillPath": throw eacces("mkdir", norm);
             // Known structural directories already exist — mkdir is a no-op.
             case "root":
             case "projectsDir":
@@ -1044,6 +1110,7 @@ export class SforaFs {
         const loc = classify(path);
         const norm = normalize(path);
         switch (loc.kind) {
+            case "skillPath": throw eacces("unlink", norm);
             case "postFile": {
                 const exists = (await this.#matchEntry(loc.slug, loc.dir, loc.filename)) !==
                     undefined;
@@ -1249,6 +1316,7 @@ export class SforaFs {
             paths.add(`/projects/${slug}/drafts`);
             paths.add(`/projects/${slug}/docs`);
             paths.add(`/projects/${slug}/artifacts`);
+            paths.add(`/projects/${slug}/skills`);
             paths.add(`/projects/${slug}/library`);
             paths.add(`/projects/${slug}/library/documents`);
             paths.add(`/projects/${slug}/library/files`);

package/dist/api-client.d.ts

@@ -389,6 +389,8 @@ export interface BlockConflict {
 export declare function blockConflictFrom(error: unknown): BlockConflict | null;
 /** Options every markdown write door takes. */
 export interface WriteOptions {
+    /** Whole-document revision from readPathSnapshot; rejects concurrent changes. */
+    expectedRevision?: number;
     /**
      * Write ONE block instead of the whole file — the id from `?view=blocks`.
      *
@@ -456,6 +458,27 @@ export declare class SforaApiClient {
      * A 409 from a `?block=` write throws a {@link SforaApiError} carrying the
      * server's recovery payload; read it with {@link blockConflictFrom}.
      */
+    listSkillDirectories(project: string): Promise<{
+        directories: Array<{
+            name: string;
+            version: number;
+        }>;
+    }>;
+    readSkillManifest(project: string, name: string): Promise<{
+        files: Array<{
+            path: string;
+            sha256: string;
+            size: number;
+            executable: boolean;
+        }>;
+        version: number;
+        hash: string;
+    }>;
+    readSkillFile(project: string, name: string, path: string): Promise<Uint8Array>;
+    readPathSnapshot(fsPath: string): Promise<{
+        content: string;
+        revision: number | null;
+    }>;
     writePath(fsPath: string, markdown: string, options?: WriteOptions): Promise<WriteResult & Partial<CardWriteResult>>;
     /** `DELETE …/(posts|drafts)/:filename.md` — soft-deletes the matched post. */
     deletePost(projectSlug: string, kind: PostKind, filename: string): Promise<void>;

package/dist/api-client.js

@@ -81,9 +81,15 @@ function routeBase(kind) {
 }
 /** `?block=<id>` when one was asked for, and nothing at all when it wasn't. */
 function blockQuery(options) {
-    return options?.blockId
-        ? `?block=${encodeURIComponent(options.blockId)}`
-        : "";
+    const query = new URLSearchParams();
+    if (options?.blockId)
+        query.set("block", options.blockId);
+    if (options?.expectedRevision !== undefined) {
+        if (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision < 0)
+            throw new Error("Expected revision must be a non-negative integer.");
+        query.set("expectedRevision", String(options.expectedRevision));
+    }
+    return query.size ? `?${query}` : "";
 }
 export class SforaApiClient {
     #baseUrl;
@@ -311,6 +317,26 @@ export class SforaApiClient {
      * A 409 from a `?block=` write throws a {@link SforaApiError} carrying the
      * server's recovery payload; read it with {@link blockConflictFrom}.
      */
+    async listSkillDirectories(project) {
+        return this.#json(`/v1/fs/projects/${encodeURIComponent(project)}/skills`);
+    }
+    async readSkillManifest(project, name) {
+        return this.#json(`/v1/fs/projects/${encodeURIComponent(project)}/skills/${encodeURIComponent(name)}`);
+    }
+    async readSkillFile(project, name, path) {
+        const response = await this.#request("GET", `/v1/fs/projects/${encodeURIComponent(project)}/skills/${encodeURIComponent(name)}/${path.split("/").map(encodeURIComponent).join("/")}`);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async readPathSnapshot(fsPath) {
+        const response = await this.#request("GET", fsRequestPath(fsPath));
+        const advertised = response.headers.get("x-sfora-revision");
+        const etag = response.headers.get("etag")?.replace(/^W\//, "").replaceAll('"', "");
+        const raw = advertised !== null && /^\d+$/.test(advertised)
+            ? advertised : etag?.match(/^(\d+)(?:-(?:gzip|br))?$/)?.[1];
+        const numeric = raw === undefined ? NaN : Number(raw);
+        const revision = Number.isSafeInteger(numeric) && numeric >= 0 ? numeric : null;
+        return { content: await response.text(), revision };
+    }
     async writePath(fsPath, markdown, options) {
         const res = await this.#request("PUT", `${fsRequestPath(fsPath)}${blockQuery(options)}`, markdown);
         return this.#jsonFrom(res);

package/dist/block-commands.d.ts

@@ -71,6 +71,7 @@ export declare function blocksCommand(client: SforaApiClient, fsPath: string, op
  */
 export declare function putCommand(client: SforaApiClient, fsPath: string, body: string, options?: {
     blockId?: string;
+    expectedRevision?: number;
     json?: boolean;
     /**
      * The run's presence latch. Omitted means "this call is the run" — a

package/dist/block-commands.js

@@ -106,6 +106,7 @@ export async function putCommand(client, fsPath, body, options = {}) {
     try {
         const result = await client.writePath(fsPath, body, {
             blockId: options.blockId,
+            ...(options.expectedRevision !== undefined ? { expectedRevision: options.expectedRevision } : {}),
         });
         const info = client.takeResponseInfo();
         if (options.json)

package/dist/cli-args.d.ts

@@ -6,6 +6,10 @@
  * process — argv in, a parsed shape out.
  */
 export interface CliArgs {
+    skillsTarget?: string;
+    skillVersion?: number;
+    expectedVersion?: number;
+    expectedRevision?: number;
     command?: string;
     rest: string[];
     org?: string;

package/dist/cli-args.js

@@ -13,6 +13,14 @@ export function parseArgs(argv) {
             args.mcp = true;
         else if (a === "--help" || a === "-h")
             args.help = true;
+        else if (a === "--skills-target")
+            args.skillsTarget = argv[++i];
+        else if (a === "--version")
+            args.skillVersion = Number(argv[++i]);
+        else if (a === "--expected-version")
+            args.expectedVersion = Number(argv[++i]);
+        else if (a === "--expected-revision")
+            args.expectedRevision = Number(argv[++i]);
         else if (a === "--org")
             args.org = argv[++i];
         else if (a.startsWith("--org="))

package/dist/cli.js

@@ -6,9 +6,11 @@
  *   SFORA_API_KEY=sk_… SFORA_URL=http://localhost:2222 sfora --org test
  *   sfora --mcp        # MCP stdio server for Claude/Cursor
  */
+import { CLI_VERSION } from "./version.js";
+import { runSkillsCommand, SKILLS_HELP } from "./skills-command.js";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
-import { readFile as readLocalFile } from "node:fs/promises";
+import { realpath, readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { taskUploadFilename } from "./format/taskUploadFilename.js";
 import { createSforaShell, createLocalShell, SforaApiError, } from "./index.js";
@@ -19,7 +21,7 @@ import { colors, ndjson, presenceRecords, renderPresence, renderWriteEffect, url
 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";
+import { readConfig, updateConfig, resolveSettings, upsertProfile, effectiveProfiles, profileKey, DEFAULT_URL, } from "./config.js";
 import { parseArgs } from "./cli-args.js";
 import { awaitReplyLoop, capitalizeName, chatMessageJson, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
@@ -57,6 +59,7 @@ Browse & read:
   sfora cat <path>                    Print a file's markdown
   sfora url <path>                    Print the web URL for a path
   sfora open <path>                   Open that URL in your browser
+  sfora desktop <file.md>             Open local Markdown in Sfora for macOS
   sfora                               Open the interactive shell
 
   Add --json to any list command (projects/posts/tasks/ls/me) for
@@ -177,12 +180,9 @@ async function runInit(args) {
         process.exitCode = 1;
         return;
     }
-    const { cfg: next, key: profile } = upsertProfile(cfg, {
-        url,
-        org: org || cfg.org,
-        apiKey: key,
-    });
-    const path = await writeConfig(next);
+    const identity = { url, org: org || cfg.org, apiKey: key };
+    const profile = profileKey(identity.url, identity.org);
+    const path = await updateConfig(current => upsertProfile(current, identity).cfg);
     console.log(`${colors.green}✓${colors.reset} Saved ${path} ${colors.dim}(${profile})${colors.reset}`);
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -251,30 +251,14 @@ async function runLogin(args, baseUrl) {
             continue;
         }
         if (data.status === "approved" && data.apiKey) {
-            const cfg = await readConfig();
-            let next;
-            if (args.bot) {
-                // Save under the bot's slot; keep the user's personal key intact.
-                next = {
-                    ...cfg,
-                    url: base,
-                    bots: {
-                        ...cfg.bots,
-                        [args.bot]: { apiKey: data.apiKey, org: data.orgSlug ?? undefined },
-                    },
-                };
-            }
-            else {
-                // Add/update this deployment+org as its own profile instead of
-                // overwriting one shared key — so logging in here never invalidates the
-                // key you hold for another deployment.
-                next = upsertProfile(cfg, {
-                    url: base,
-                    org: data.orgSlug ?? undefined,
-                    apiKey: data.apiKey,
-                }).cfg;
-            }
-            const path = await writeConfig(next);
+            const approvedKey = data.apiKey;
+            const botName = args.bot;
+            const path = await updateConfig(current => botName ? {
+                ...current, url: base,
+                bots: { ...current.bots, [botName]: { apiKey: approvedKey, org: data.orgSlug ?? undefined } },
+            } : upsertProfile(current, {
+                url: base, org: data.orgSlug ?? undefined, apiKey: approvedKey,
+            }).cfg);
             console.log(`\n${colors.green}✓${colors.reset} Logged in as ${data.name ?? "you"}${data.orgSlug ? ` ${colors.dim}(${data.orgSlug})${colors.reset}` : ""}${args.bot ? ` ${colors.dim}[bot: ${args.bot}]${colors.reset}` : ""} — saved ${path}`);
             return;
         }
@@ -498,6 +482,7 @@ async function runVerb(args, fs, client) {
             : await readStdin();
         return writeCommandOutput(await putCommand(client, path, body, {
             blockId: args.block,
+            expectedRevision: args.expectedRevision,
             json: args.json,
             presence: runPresence,
         }));
@@ -1492,9 +1477,26 @@ Everything is git-versioned with your repo. ${colors.dim}Connect a team later wi
 Type ${colors.cyan}exit${colors.reset} to quit.
 `;
 async function main() {
+    if (["--version", "-v"].includes(process.argv[2] ?? "")) {
+        console.log(`sfora-cli ${CLI_VERSION}`);
+        return;
+    }
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
-        process.stdout.write(HELP);
+        process.stdout.write(HELP + "\n" + SKILLS_HELP);
+        return;
+    }
+    if (args.command === "desktop") {
+        if (process.platform !== "darwin")
+            throw new Error("Desktop opening is currently supported on macOS.");
+        if (!args.rest.length)
+            throw new Error("usage: sfora desktop <file.md> [file.md ...]");
+        const paths = await Promise.all(args.rest.map(path => realpath(path)));
+        await new Promise((resolve, reject) => {
+            const child = spawn("/usr/bin/open", ["-a", "Sfora", "--", ...paths], { stdio: "inherit" });
+            child.once("error", reject);
+            child.once("exit", code => code === 0 ? resolve() : reject(new Error("Could not open Sfora. Install Sfora.app in Applications first.")));
+        });
         return;
     }
     if (args.command === "init") {
@@ -1510,6 +1512,10 @@ async function main() {
     }
     const cfg = await readConfig();
     const settings = resolveSettings({ url: args.url, apiKey: args.key, org: args.org, bot: args.bot }, cfg);
+    if (args.command === "skills") {
+        await runSkillsCommand(args, settings);
+        return;
+    }
     const { url: baseUrl, apiKey } = settings;
     // Once per invocation: what kind of client is on the line. The api client
     // sends it on every request (`X-Sfora-Client`), so every creation door

package/dist/config.d.ts

@@ -17,6 +17,8 @@ export interface SforaConfig {
 export declare const CONFIG_PATH: string;
 export declare const DEFAULT_URL = "https://www.sfora.ai";
 export declare function readConfig(): Promise<SforaConfig>;
+export declare function updateConfig(update: (current: SforaConfig) => SforaConfig): Promise<string>;
+/** Merge profile maps under a process lock for older callers holding a snapshot. */
 export declare function writeConfig(cfg: SforaConfig): Promise<string>;
 export interface ResolvedSettings {
     url: string;

package/dist/config.js

@@ -11,7 +11,8 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+import { readFile, mkdir } from "node:fs/promises";
+import { atomicWrite, withLocalLock } from "./local-core/files.js";
 const CONFIG_DIR = join(homedir(), ".sfora");
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 // Production sfora. Local development of sfora itself overrides via --url or
@@ -27,12 +28,20 @@ export async function readConfig() {
         return {};
     }
 }
+export async function updateConfig(update) {
+    await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    return withLocalLock(CONFIG_PATH, async () => {
+        const next = update(await readConfig());
+        await atomicWrite(CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`, 0o600);
+        return CONFIG_PATH;
+    });
+}
+/** Merge profile maps under a process lock for older callers holding a snapshot. */
 export async function writeConfig(cfg) {
-    await mkdir(CONFIG_DIR, { recursive: true });
-    await writeFile(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
-    // The file holds an API key — keep it owner-readable only.
-    await chmod(CONFIG_PATH, 0o600).catch(() => { });
-    return CONFIG_PATH;
+    return updateConfig(current => ({ ...current, ...cfg,
+        profiles: { ...current.profiles, ...cfg.profiles },
+        bots: { ...current.bots, ...cfg.bots },
+    }));
 }
 // First non-empty value (treats "" / undefined as unset).
 function pick(...vals) {

package/dist/format/cardMarkdown.d.ts

@@ -16,6 +16,7 @@ export interface MarkdownCardInput {
     resolution?: string;
     scope?: "out";
     blockedBy?: number[];
+    parentCardId?: string;
 }
 export interface MarkdownBoardRef {
     _id: string;

package/dist/format/cardMarkdown.js

@@ -63,6 +63,7 @@ export function cardToMarkdown(card, board, column, commentsCount) {
     const fm = serializeFrontmatter([
         ["id", card._id],
         ["number", String(card.number)],
+        ["parentCardId", card.parentCardId],
         ["board", board?.slug ?? board?.name ?? ""],
         ["boardId", board?._id ?? ""],
         ["column", column?.name ?? ""],

package/dist/index.d.ts

@@ -77,3 +77,4 @@ export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, type WatchDeps, type Watch
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, type DocPing, } from "./render.js";
 export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug, chatMessageJson, chatTailLoop, awaitReplyLoop, type ChatTailDeps, type ChatTailOptions, type AwaitReplyDeps, type AwaitReplyOptions, type AwaitReplyResult, } from "./chat.js";
 export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, type AskWaitDeps, type AskWaitOptions, type AskWaitResult, } from "./ask.js";
+export { SkillsClient } from "./skills-client.js";

package/dist/index.js

@@ -60,3 +60,4 @@ export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, } from "./render.js";
 export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug, chatMessageJson, chatTailLoop, awaitReplyLoop, } from "./chat.js";
 export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, } from "./ask.js";
+export { SkillsClient } from "./skills-client.js";

package/dist/local/workspace.d.ts

@@ -1,19 +1,3 @@
-/**
- * LocalWorkspace — the OSS local mode. A `.sfora/` directory in your repo is
- * the workspace: tasks, posts, and docs are plain markdown files on disk, in
- * exactly the same format the cloud serves over /v1/fs (shared `../format`
- * core), so `cp` is a migration.
- *
- *   .sfora/
- *     board/01-todo/0001-fix-login.md   tasks — NNNN-<slug>.md per column dir
- *     posts/2026-07-02-standup.md       posts — YYYY-MM-DD-<slug>.md
- *     docs/architecture.md              docs  — <slug>.md
- *
- * This module owns the *semantics* (scaffolding, card numbering, canonical
- * filenames, listings). The interactive shell needs no virtualization locally —
- * just-bash's ReadWriteFs jails a real directory, and real `mv` between column
- * dirs IS a card move.
- */
 /** Directory name that marks a local sfora workspace. */
 export declare const WORKSPACE_DIR = ".sfora";
 /**