sfora-cli 0.15.0 → 0.17.0

package/dist/shell-commands.d.ts

@@ -1,5 +1,7 @@
 /**
- * The sfora-native commands inside the shell: `blocks`, `put`, `url`.
+ * The sfora-native commands inside the shell: `blocks`, `put`, `url`,
+ * `backlinks`, `attachments` (card #822, list only), and
+ * `typing` (card #668 — the agent typing signal, the same verb as the CLI's).
  *
  * Card #333's "and the fs shell equivalent". The shell already writes whole
  * files (`echo '# Title' > /projects/x/docs/y.md` is a PUT), but it had no way
@@ -19,6 +21,10 @@ interface ParsedArgs {
     positional: string[];
     blockId?: string;
     json: boolean;
+    /** `typing --for <secs>` */
+    seconds?: string;
+    /** `typing --stop` */
+    stop: boolean;
 }
 export declare function parseShellArgs(args: string[]): ParsedArgs;
 /**

package/dist/shell-commands.js

@@ -1,5 +1,7 @@
 /**
- * The sfora-native commands inside the shell: `blocks`, `put`, `url`.
+ * The sfora-native commands inside the shell: `blocks`, `put`, `url`,
+ * `backlinks`, `attachments` (card #822, list only), and
+ * `typing` (card #668 — the agent typing signal, the same verb as the CLI's).
  *
  * Card #333's "and the fs shell equivalent". The shell already writes whole
  * files (`echo '# Title' > /projects/x/docs/y.md` is a PUT), but it had no way
@@ -12,9 +14,11 @@
  * k7f3a2cx` is the loop this exists for.
  */
 import { decodeBytesToUtf8 } from "just-bash";
-import { blocksCommand, presenceNotice, putCommand, resolveFsPath, urlCommand, } from "./block-commands.js";
+import { blocksCommand, backlinksCommand, presenceNotice, putCommand, resolveFsPath, urlCommand, } from "./block-commands.js";
+import { TYPING_USAGE, typingCommand } from "./typing.js";
+import { attachmentsCommand } from "./attachments.js";
 export function parseShellArgs(args) {
-    const parsed = { positional: [], json: false };
+    const parsed = { positional: [], json: false, stop: false };
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (a === "--json")
@@ -24,6 +28,12 @@ export function parseShellArgs(args) {
         else if (a.startsWith("--block=")) {
             parsed.blockId = a.slice("--block=".length);
         }
+        else if (a === "--for")
+            parsed.seconds = args[++i];
+        else if (a.startsWith("--for="))
+            parsed.seconds = a.slice("--for=".length);
+        else if (a === "--stop")
+            parsed.stop = true;
         else
             parsed.positional.push(a);
     }
@@ -80,6 +90,31 @@ export function sforaShellCommands(client, presence = presenceNotice()) {
                 }));
             },
         },
+        {
+            name: "backlinks",
+            async execute(args, ctx) {
+                const { positional, json } = parseShellArgs(args);
+                if (!positional[0])
+                    return usage("usage: backlinks <path> [--json]");
+                return toExec(await backlinksCommand(client, resolveFsPath(ctx.cwd, positional[0]), {
+                    json,
+                }));
+            },
+        },
+        {
+            // Card #822. List only: the shell's fs is the workspace, so there is no
+            // local disk for `--out` — `sfora attachments <post> --out <dir>` is the
+            // CLI verb that writes the files.
+            name: "attachments",
+            async execute(args, ctx) {
+                const { positional, json } = parseShellArgs(args);
+                if (!positional[0])
+                    return usage("usage: attachments <post path> [--json]");
+                return toExec(await attachmentsCommand(client, resolveFsPath(ctx.cwd, positional[0]), {
+                    json,
+                }));
+            },
+        },
         {
             name: "put",
             async execute(args, ctx) {
@@ -93,6 +128,17 @@ export function sforaShellCommands(client, presence = presenceNotice()) {
                 return toExec(await putCommand(client, resolveFsPath(ctx.cwd, positional[0]), body, { blockId, json, presence }));
             },
         },
+        {
+            // Rooms are named, not pathed (as `sfora chat` names them): the shell
+            // has no room files to write to, so this is the one verb that takes one.
+            name: "typing",
+            async execute(args) {
+                const { positional, json, seconds, stop } = parseShellArgs(args);
+                if (!positional[0])
+                    return usage(TYPING_USAGE);
+                return toExec(await typingCommand(client, positional[0], { seconds, stop, json }));
+            },
+        },
         {
             name: "url",
             async execute(args, ctx) {

package/dist/skills-client.d.ts

@@ -1,5 +1,14 @@
 import { type SkillBundle } from "./local-core/skills.js";
 import type { ResolvedSettings } from "./config.js";
+import { type PublishedSkillSnapshot } from "./local-core/skill-sync.js";
+export declare class SkillsApiError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+export declare class SkillPublicationUnavailableError extends Error {
+    readonly code: 'SKILL_NOT_FOUND' | 'SKILL_NOT_PUBLISHED';
+    constructor(code: 'SKILL_NOT_FOUND' | 'SKILL_NOT_PUBLISHED', message: string);
+}
 export declare class SkillsClient {
     private readonly settings;
     constructor(settings: ResolvedSettings);
@@ -13,9 +22,11 @@ export declare class SkillsClient {
         [key: string]: unknown;
     }>;
     download(project: string, name: string, version?: number): Promise<SkillBundle>;
-    saveDraft(project: string, bundle: SkillBundle, expectedVersion: number, expectedRevision?: number): Promise<{
+    /** Pin a published revision and verify IDs/hash; lookup labels confer no update authority. */
+    snapshot(project: string, name: string): Promise<PublishedSkillSnapshot>;
+    saveDraft(project: string, bundle: SkillBundle, expectedVersion: number, expectedRevision?: number, expectedSkillId?: string): Promise<{
         draftRevision: number;
         [key: string]: unknown;
     }>;
-    publish(project: string, name: string, expectedVersion: number, expectedRevision?: number): Promise<unknown>;
+    publish(project: string, name: string, expectedVersion: number, expectedRevision?: number, expectedSkillId?: string): Promise<unknown>;
 }

package/dist/skills-client.js

@@ -1,4 +1,20 @@
 import { validateSkillBundle } from "./local-core/skills.js";
+import { SforaApiClient } from "./api-client.js";
+import { validatePublishedSkillSnapshot } from "./local-core/skill-sync.js";
+export class SkillsApiError extends Error {
+    status;
+    constructor(status, body) {
+        super(`Skills API ${status}: ${body}`);
+        this.status = status;
+    }
+}
+export class SkillPublicationUnavailableError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
 export class SkillsClient {
     settings;
     constructor(settings) {
@@ -11,7 +27,7 @@ export class SkillsClient {
             ...init, headers: { Authorization: `Bearer ${this.settings.apiKey}`, "Content-Type": "application/json", "X-Sfora-Client": "cli", ...init?.headers },
         });
         if (!response.ok)
-            throw new Error(`Skills API ${response.status}: ${await response.text()}`);
+            throw new SkillsApiError(response.status, await response.text());
         return await response.json();
     }
     list(project) { return this.request(`/v1/skills?${new URLSearchParams({ project })}`); }
@@ -26,11 +42,47 @@ export class SkillsClient {
         validateSkillBundle(bundle);
         return bundle;
     }
-    saveDraft(project, bundle, expectedVersion, expectedRevision) {
+    /** Pin a published revision and verify IDs/hash; lookup labels confer no update authority. */
+    async snapshot(project, name) {
+        if (!this.settings.apiKey)
+            throw new Error("Run sfora login to connect to cloud Skills.");
+        const me = await new SforaApiClient({ baseUrl: this.settings.url, apiKey: this.settings.apiKey }).readMe();
+        const accountId = /^memberId: ([a-zA-Z0-9_-]+)$/m.exec(me)?.[1];
+        if (!accountId)
+            throw new Error('Cloud identity response is missing a member ID.');
+        let detail;
+        try {
+            detail = await this.detail(project, name);
+        }
+        catch (error) {
+            if (error instanceof SkillsApiError && error.status === 404)
+                throw new SkillPublicationUnavailableError('SKILL_NOT_FOUND', 'This project has no published skill with that name.');
+            throw error;
+        }
+        const skill = detail.skill;
+        if (![skill._id, skill.orgId, skill.projectId].every(v => typeof v === 'string' && v.length > 0))
+            throw new Error('Cloud skill response is missing qualified identity fields.');
+        if (!Number.isSafeInteger(skill.version) || skill.version < 1)
+            throw new SkillPublicationUnavailableError('SKILL_NOT_PUBLISHED', 'This skill has no published version to compare.');
+        const versions = detail.versions;
+        const revision = Array.isArray(versions) ? versions.find(v => v.version === skill.version && v.skillId === skill._id) : undefined;
+        if (!revision || typeof revision.hash !== 'string')
+            throw new Error('Cloud skill response is missing the published revision.');
+        const bundle = await this.download(project, name, skill.version);
+        const snapshot = {
+            remote: { deployment: new URL(this.settings.url).origin, organizationId: skill.orgId, projectId: skill.projectId, skillId: skill._id },
+            accountId, locator: { project, name }, revision: { hash: revision.hash, cloudVersion: skill.version, contentPolicy: 'bundle-v1' },
+            draftRevision: skill.draftRevision, hasDraft: !!skill.draftStorageId, draftHash: skill.draftHash,
+            supportsIdentityGuards: Array.isArray(detail.capabilities) && detail.capabilities.includes('qualified-skill-write-v1'), bundle,
+        };
+        validatePublishedSkillSnapshot(snapshot);
+        return snapshot;
+    }
+    saveDraft(project, bundle, expectedVersion, expectedRevision, expectedSkillId) {
         validateSkillBundle(bundle);
-        return this.request("/v1/skills", { method: "POST", body: JSON.stringify({ project, name: bundle.name, bundle, expectedVersion, expectedRevision }) });
+        return this.request("/v1/skills", { method: "POST", body: JSON.stringify({ project, name: bundle.name, bundle, expectedVersion, expectedRevision, expectedSkillId }) });
     }
-    publish(project, name, expectedVersion, expectedRevision) {
-        return this.request("/v1/skills/publish", { method: "POST", body: JSON.stringify({ project, name, expectedVersion, expectedRevision }) });
+    publish(project, name, expectedVersion, expectedRevision, expectedSkillId) {
+        return this.request("/v1/skills/publish", { method: "POST", body: JSON.stringify({ project, name, expectedVersion, expectedRevision, expectedSkillId }) });
     }
 }

package/dist/skills-command.d.ts

@@ -1,4 +1,4 @@
 import type { CliArgs } from "./cli-args.js";
 import type { ResolvedSettings } from "./config.js";
-export declare const SKILLS_HELP = "Skills:\n  sfora skills scan [root ...] --json          Discover complete local skill bundles\n  sfora skills list --project <slug>           List cloud project skills\n  sfora skills push <folder> --project <slug> --expected-version <N> [--expected-revision <N>]\n                                              Upload draft and publish (0 for a new skill)\n  sfora skills pull <name> <bundle.json> --project <slug> [--version <N>]\n  sfora skills install <name> --project <slug> --skills-target <directory> [--version <N>]\n  sfora skills install-file <bundle.json> --skills-target <directory>\n  sfora skills diff <folder> <name> --project <slug> [--version <N>]\n  sfora skills uninstall <installed-folder>   Remove only an unchanged Sfora-owned install\n";
+export declare const SKILLS_HELP = "Skills:\n  sfora skills inventory --json               Persistent local inventory with warnings and identities\n  sfora skills roots [add <folder> [label] | add-project <folder> [label] | remove <id>]\n                                              Manage registered discovery folders (never deletes files)\n  sfora skills scan [root ...] --json          Discover complete local skill bundles\n  sfora skills list --project <slug>           List cloud project skills\n  sfora skills index --json                  Read cached local inventory without scanning\n  sfora skills operations                    List durable transfer outcomes and recovery needs\n  sfora skills queue <plan.json>             Queue a reviewed push, pull or install\n  sfora skills cancel <operation-id>         Cancel an unstarted operation\n  sfora skills apply <plan.json|operation-id> Execute a reviewed plan\n  sfora skills recover <operation-id>        Reconcile an interrupted operation\n  sfora skills apply-batch <ids.json>        Run queued operation IDs with per-item outcomes\n  sfora skills recover-batch <ids.json>      Resume incomplete items without replaying successes\n  sfora skills bindings                      List explicit cloud mappings and baselines\n  sfora skills bind <location-id> <cloud-name> --project <slug>\n                                              Explicitly adopt a published cloud identity\n  sfora skills status <binding-id>            Compare current files with the bound published revision\n  sfora skills plan <binding-id> <push|pull>   Preview IDs, hashes, conflicts and per-file changes\n  sfora skills plan-install <name> --project <slug> --skills-target <existing-directory>\n                                              Preview a new installation without modifying files\n  sfora skills relocate <location-id> <folder> Preserve identity after an explicit folder move\n  sfora skills push <folder> --project <slug> --expected-version <N> [--expected-revision <N>]\n                                              Upload draft and publish (0 for a new skill)\n  sfora skills pull <name> <bundle.json> --project <slug> [--version <N>]\n  sfora skills install <name> --project <slug> --skills-target <directory> [--version <N>]\n  sfora skills install-file <bundle.json> --skills-target <directory>\n  sfora skills diff <folder> <name> --project <slug> [--version <N>]\n  sfora skills uninstall <installed-folder>   Remove only an unchanged Sfora-owned install\n  sfora skills packet install --harness <claude-code|codex|agents> [--skills-target <dir>] [--dry-run]\n                                              Install sfora's own agent skills into that agent's\n                                              user skills folder (never overwrites a folder it\n                                              did not install, or one with local changes)\n";
 export declare function runSkillsCommand(args: CliArgs, settings: ResolvedSettings): Promise<void>;

package/dist/skills-command.js

@@ -1,9 +1,34 @@
-import { readFile } from "node:fs/promises";
-import { diffSkillBundles, installSkillBundle, readSkillBundle, scanLocalSkills, uninstallSkill, validateSkillBundle } from "./local-core/index.js";
+import { dirname, join } from "node:path";
+import { readFile, realpath } from "node:fs/promises";
+import { diffSkillBundles, installSkillBundle, inspectSkillTarget, readSkillBundle, discoverSkills, SkillService, uninstallSkill, validateSkillBundle, validateSkillFrontmatter } from "./local-core/index.js";
+import { PACKET_USAGE, packetInstallCommand } from "./skills-packet.js";
+import { SkillOperationJournal } from "./local-core/skill-operations.js";
+import { SkillOperationExecutor } from "./local-core/skill-executor.js";
+import { defaultSkillCatalogPath } from "./local-core/skill-store.js";
 import { SkillsClient } from "./skills-client.js";
+import { SkillBindingService, assertSkillBindingSnapshot, compareSkillStates, planSkillTransfer, planSkillInstallation } from './local-core/skill-sync.js';
 export const SKILLS_HELP = `Skills:
+  sfora skills inventory --json               Persistent local inventory with warnings and identities
+  sfora skills roots [add <folder> [label] | add-project <folder> [label] | remove <id>]
+                                              Manage registered discovery folders (never deletes files)
   sfora skills scan [root ...] --json          Discover complete local skill bundles
   sfora skills list --project <slug>           List cloud project skills
+  sfora skills index --json                  Read cached local inventory without scanning
+  sfora skills operations                    List durable transfer outcomes and recovery needs
+  sfora skills queue <plan.json>             Queue a reviewed push, pull or install
+  sfora skills cancel <operation-id>         Cancel an unstarted operation
+  sfora skills apply <plan.json|operation-id> Execute a reviewed plan
+  sfora skills recover <operation-id>        Reconcile an interrupted operation
+  sfora skills apply-batch <ids.json>        Run queued operation IDs with per-item outcomes
+  sfora skills recover-batch <ids.json>      Resume incomplete items without replaying successes
+  sfora skills bindings                      List explicit cloud mappings and baselines
+  sfora skills bind <location-id> <cloud-name> --project <slug>
+                                              Explicitly adopt a published cloud identity
+  sfora skills status <binding-id>            Compare current files with the bound published revision
+  sfora skills plan <binding-id> <push|pull>   Preview IDs, hashes, conflicts and per-file changes
+  sfora skills plan-install <name> --project <slug> --skills-target <existing-directory>
+                                              Preview a new installation without modifying files
+  sfora skills relocate <location-id> <folder> Preserve identity after an explicit folder move
   sfora skills push <folder> --project <slug> --expected-version <N> [--expected-revision <N>]
                                               Upload draft and publish (0 for a new skill)
   sfora skills pull <name> <bundle.json> --project <slug> [--version <N>]
@@ -11,6 +36,10 @@ export const SKILLS_HELP = `Skills:
   sfora skills install-file <bundle.json> --skills-target <directory>
   sfora skills diff <folder> <name> --project <slug> [--version <N>]
   sfora skills uninstall <installed-folder>   Remove only an unchanged Sfora-owned install
+  sfora skills packet install --harness <claude-code|codex|agents> [--skills-target <dir>] [--dry-run]
+                                              Install sfora's own agent skills into that agent's
+                                              user skills folder (never overwrites a folder it
+                                              did not install, or one with local changes)
 `;
 export async function runSkillsCommand(args, settings) {
     const [verb, first, second] = args.rest;
@@ -21,8 +50,35 @@ export async function runSkillsCommand(args, settings) {
     const print = (value) => console.log(JSON.stringify(value, null, args.json ? undefined : 2));
     const need = (value, label) => { if (!value)
         throw new Error(`${label} is required.\n${SKILLS_HELP}`); return value; };
-    if (verb === "scan") {
-        print(await scanLocalSkills(args.rest.length > 1 ? args.rest.slice(1) : undefined));
+    if (verb === "roots") {
+        const service = new SkillService();
+        if (!first)
+            print(await service.roots());
+        else if (first === "add" || first === "add-project")
+            print(await service.registerRoot(need(second, "Folder"), args.rest[3], first === "add-project" ? "project" : "custom"));
+        else if (first === "remove") {
+            await service.removeRoot(need(second, "Root ID"));
+            print({ removed: second });
+        }
+        else
+            throw new Error("Use skills roots, skills roots add <folder> [label], or skills roots remove <id>.");
+        return;
+    }
+    if (verb === "index") {
+        print(await new SkillService().cachedInventory());
+        return;
+    }
+    if (verb === "inventory" || verb === "scan") {
+        const result = verb === "scan" && args.rest.length > 1
+            ? await discoverSkills(args.rest.slice(1).map(path => ({ path, label: "Chosen folder", depth: 4 })))
+            : await new SkillService().inventory();
+        if (verb === "scan") {
+            print(result.skills);
+            if (result.warnings.length)
+                console.error(JSON.stringify({ warnings: result.warnings }));
+        }
+        else
+            print(result);
         return;
     }
     if (verb === "uninstall") {
@@ -30,6 +86,109 @@ export async function runSkillsCommand(args, settings) {
         print({ uninstalled: first });
         return;
     }
+    if (['operations', 'queue', 'cancel', 'apply', 'recover', 'apply-batch', 'recover-batch'].includes(verb)) {
+        const journal = new SkillOperationJournal(join(dirname(defaultSkillCatalogPath()), 'operations.sqlite'));
+        if (verb === 'operations') {
+            print(await journal.list());
+            return;
+        }
+        if (verb === 'cancel') {
+            print(await journal.cancel(need(first, 'Operation ID')));
+            return;
+        }
+        if (verb === 'queue') {
+            print(await journal.create(JSON.parse(await readFile(need(first, 'Plan JSON'), 'utf8'))));
+            return;
+        }
+        const service = new SkillService();
+        const client = new SkillsClient(settings);
+        const executor = new SkillOperationExecutor(service.store, journal, client);
+        if (verb === 'apply-batch' || verb === 'recover-batch') {
+            const ids = JSON.parse(await readFile(need(first, 'Operation IDs JSON'), 'utf8'));
+            const controller = new AbortController();
+            const stop = () => { controller.abort(); console.error('Stopping after the current item; unstarted work will be cancelled.'); };
+            process.once('SIGINT', stop);
+            try {
+                const results = await executor.batch(ids, { recover: verb === 'recover-batch', signal: controller.signal });
+                print(results);
+                if (results.some(r => r.error))
+                    process.exitCode = 1;
+            }
+            finally {
+                process.removeListener('SIGINT', stop);
+            }
+            return;
+        }
+        const operation = verb === 'apply' && !/^[a-f0-9-]{36}$/.test(first ?? '') ? await journal.create(JSON.parse(await readFile(need(first, 'Plan JSON'), 'utf8'))) : undefined;
+        const id = operation?.id ?? need(first, 'Operation ID');
+        try {
+            print(await executor.apply(id, verb === 'recover'));
+        }
+        catch (error) {
+            throw new Error(`${error.message} Operation ${id} was retained; inspect skills operations, then use skills recover ${id}.`);
+        }
+        return;
+    }
+    if (['bindings', 'bind', 'status', 'plan', 'relocate'].includes(verb)) {
+        const service = new SkillService();
+        const bindings = new SkillBindingService(service.store);
+        if (verb === 'bindings') {
+            print(await bindings.list());
+            return;
+        }
+        if (verb === 'relocate') {
+            print(await service.relocateLocation(need(first, 'Location ID'), need(second, 'Folder')));
+            return;
+        }
+        const catalog = await service.store.read();
+        const binding = verb === 'bind' ? undefined : catalog.bindings.find(b => b.id === need(first, 'Binding ID'));
+        if (verb !== 'bind' && !binding)
+            throw new Error('Skill binding not found.');
+        if (binding && args.project && args.project !== binding.locator.project)
+            throw new Error('--project differs from the explicit skill binding.');
+        const location = catalog.locations.find(l => verb === 'bind' ? l.id === first : l.skillId === binding.localSkillId);
+        if (!location)
+            throw new Error('Local skill location not found. Register its folder and refresh the inventory first.');
+        if (verb === 'plan' && second !== 'push' && second !== 'pull')
+            throw new Error('Choose skills plan <binding-id> <push|pull>.');
+        const client = new SkillsClient(settings);
+        const snapshot = await client.snapshot(binding?.locator.project ?? need(args.project, '--project'), binding?.locator.name ?? need(second, 'Cloud skill name'));
+        if (binding)
+            assertSkillBindingSnapshot(binding, snapshot);
+        let local;
+        try {
+            local = { state: 'available', bundle: await readSkillBundle(location.path) };
+        }
+        catch (error) {
+            local = { state: error.code === 'ENOENT' ? 'missing' : 'unavailable', reason: error.message };
+        }
+        if (verb === 'bind') {
+            if (local.state !== 'available')
+                throw new Error(local.reason);
+            print(await bindings.adopt(location.skillId, snapshot, local.bundle));
+            return;
+        }
+        if (verb === 'status') {
+            print({ bindingId: binding.id, status: compareSkillStates(local, { state: 'available', bundle: snapshot.bundle }, binding.baseline),
+                local: local.state === 'available' ? { state: local.state, hash: local.bundle.hash } : local, remote: snapshot.revision, baseline: binding.baseline ?? null });
+            return;
+        }
+        const target = await inspectSkillTarget(location.path);
+        print(planSkillTransfer({ direction: second, binding: binding, location, local, remote: snapshot, ownership: target.ownership }));
+        return;
+    }
+    if (verb === "packet") {
+        if (first !== "install" || args.rest.length !== 2)
+            throw new Error(PACKET_USAGE);
+        const out = await packetInstallCommand({ harness: args.harness, skillsTarget: args.skillsTarget, dryRun: args.dryRun, json: args.json });
+        if (out.stdout)
+            process.stdout.write(out.stdout);
+        if (out.stderr)
+            process.stderr.write(out.stderr);
+        if (out.exitCode !== 0)
+            process.exitCode = out.exitCode;
+        return;
+    }
     if (verb === "install-file") {
         const bundle = JSON.parse(await readFile(need(first, "Bundle JSON"), "utf8"));
         validateSkillBundle(bundle);
@@ -38,6 +197,12 @@ export async function runSkillsCommand(args, settings) {
     }
     const project = need(args.project, "--project");
     const client = new SkillsClient(settings);
+    if (verb === 'plan-install') {
+        const remote = await client.snapshot(project, need(first, 'Skill name'));
+        const target = join(await realpath(need(args.skillsTarget, '--skills-target')), remote.bundle.name);
+        print(planSkillInstallation(remote, target, await inspectSkillTarget(target)));
+        return;
+    }
     if (verb === "list") {
         print(await client.list(project));
         return;
@@ -46,6 +211,8 @@ export async function runSkillsCommand(args, settings) {
         if (args.expectedVersion === undefined)
             throw new Error("--expected-version is required (0 for a new skill). Read the current version with skills list first.");
         const bundle = await readSkillBundle(need(first, "Skill folder"));
+        // What sfora publishes must be loadable by an agent: name and description in SKILL.md.
+        validateSkillFrontmatter(bundle);
         const draft = await client.saveDraft(project, bundle, args.expectedVersion, args.expectedRevision);
         print(await client.publish(project, bundle.name, args.expectedVersion, draft.draftRevision));
         return;

package/dist/skills-packet/sfora-asks/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sfora-asks
+description: "Use when you need a human to decide something in sfora and want to wait for the answer, or when you pick up an open ask (a unit of work up for grabs) by claiming it and later resolving it. Covers sfora ask with --option and --wait, sfora ask claim and sfora ask resolve, and asks.md. Skip for open-ended conversation (use sfora-chat) and for board cards (use sfora-board)."
+---
+
+# Ask a human, claim an ask
+
+An ask is either a question for a human, with two to four answers to pick from, or a piece of work up for grabs. Only humans answer questions. Agents claim work before doing it, so two agents never do the same job. Run `sfora …` in a shell, with `--agent <name>` on every command.
+
+## Steps
+
+1. To get a decision, ask once and wait for the answer (here, up to 10 minutes):
+
+   ```bash
+   sfora ask "<question>" --option "<answer A>" --option "<answer B>" --project hq --wait 600 --agent claude-code
+   ```
+
+2. To find work up for grabs, read the project's asks. Each open one shows its id:
+
+   ```bash
+   sfora cat /projects/hq/asks.md --agent claude-code
+   ```
+
+3. Claim the ask before you start. If someone else holds it, the claim fails with their name: stand down.
+
+   ```bash
+   sfora ask claim <ask-id> --agent claude-code
+   ```
+
+4. When the work is done, resolve it and say what you did:
+
+   ```bash
+   sfora ask resolve <ask-id> -m "<what you did, with a link>" --agent claude-code
+   ```
+
+## Guardrails
+
+- Ask a question once. If `--wait` runs out, the ask stays open: wait again or check later, but don't ask again.
+- Keep each answer under 80 characters. Two to four answers.
+- You can't claim a question: only a human answers it.
+- Only the agent that claimed an ask (or an admin) can resolve it.
+- `--for` names a person here. In `sfora typing` it means seconds.
+- `asks.md` is read-only. Claim and resolve only with `sfora ask claim` and `sfora ask resolve`.
+
+## Report
+
+Quote the question and the answer you got, or the ask you claimed and how you resolved it.
+
+Detail: `references/asks.md`.

package/dist/skills-packet/sfora-asks/references/asks.md

@@ -0,0 +1,41 @@
+# Asks in detail
+
+## A question for a human
+
+```bash
+sfora ask "<question>" --option "<answer A>" --option "<answer B>" --project hq --agent claude-code
+sfora ask "<question>" --option "<answer A>" --option "<answer B>" --for <member> --project hq --wait 600 --agent claude-code
+sfora ask "<question>" --option "<answer A>" --option "<answer B>" --room general --json --agent claude-code
+```
+
+- `--project` says which project it belongs to. `--room` also announces it in that room.
+- `--for <member>` aims it at one person by name. Any human can still answer. If the name matches several people, the CLI lists them: use the full name.
+- `--wait` with no number waits until someone answers. `--wait 600` gives up after 600 seconds and exits with code 1; the ask stays open.
+- `--json` prints the new ask's id. With `--wait`, a second JSON line arrives with the answer.
+
+Write the question so it stands on its own: the person may see it hours later, without your context. Put the answer you recommend first.
+
+## Work up for grabs
+
+An ask without `--option` is work any agent can claim:
+
+```bash
+sfora ask "<the job, in one sentence>" --project hq --agent claude-code
+```
+
+The project's open asks are listed in `asks.md`, each with its id (the long string in `POST /api/asks/<id>/claim`):
+
+```bash
+sfora cat /projects/hq/asks.md --agent claude-code
+```
+
+## Claim and resolve
+
+```bash
+sfora ask claim <ask-id> --agent claude-code
+sfora ask claim <ask-id> --json --agent claude-code
+sfora ask resolve <ask-id> -m "<what you did, with a link>" --agent claude-code
+```
+
+- A claim fails if someone else holds the ask (the error names them), if the ask is a question, or if it's no longer open. Don't retry it: pick other work.
+- Resolve only an ask you claimed. `-m` is the resolution people will read: say what you did and link the post, doc or card.

package/dist/skills-packet/sfora-board/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: sfora-board
+description: "Use when you keep a sfora project's board moving (create a card, pick up a card, move it to In progress, close it as done) or when you write or update the project's goal in plan.md. Covers sfora tasks, sfora task, sfora cat and sfora put on board and plan paths. Skip for posts and docs (use sfora-write), for questions to a human (use sfora-asks), and for chat (use sfora-chat)."
+---
+
+# Keep the board moving
+
+A card is a markdown file in a column folder: `/projects/hq/board/02-todo/0012-fix-login.md`. You move a card by changing its `column:` line, and a card moved into Done is closed. The plan's goal is one section of `plan.md`. Run `sfora …` in a shell, with `--agent <name>` on every command.
+
+## Steps
+
+1. Read the board first:
+
+   ```bash
+   sfora tasks hq --agent claude-code
+   ```
+
+2. Create a card from a local file whose H1 is the title. It lands in To do unless you name a column:
+
+   ```bash
+   sfora task fix-login.md --project hq --agent claude-code
+   sfora task fix-login.md --project hq --column in-progress --agent claude-code
+   ```
+
+3. Move a card: save it, change its `column:` line (for example to `column: In progress` or `column: Done`), and put it back to the same path:
+
+   ```bash
+   sfora cat /projects/hq/board/02-todo/<card-file>.md --agent claude-code > card.md
+   sfora put /projects/hq/board/02-todo/<card-file>.md card.md --agent claude-code
+   ```
+
+4. Write the plan's goal: save `plan.md`, edit the text under `## the goal`, and put it back:
+
+   ```bash
+   sfora cat /projects/hq/plan.md --agent claude-code > plan.md
+   sfora put /projects/hq/plan.md plan.md --agent claude-code
+   ```
+
+5. Check the result with `sfora tasks hq --agent claude-code`.
+
+## Guardrails
+
+- `--column` takes the folder name without its number: `triage`, `todo`, `in-progress`, `done`. A name that matches nothing silently puts the card in To do.
+- `column:` in the card's frontmatter takes the column's display name. A name that matches no column fails.
+- Run `sfora task` once per card. Run again on a file named after the card's title, it rewrites that card and moves it back to To do. Edit a card with `sfora put` on its path.
+- Only `## the goal` in plan.md is yours to write. The other sections are generated, and sfora ignores edits to them.
+- Move a card into Done only when the work is really done.
+
+## Report
+
+List the cards you created or moved, with their numbers and columns, and quote the goal if you changed it.
+
+Detail: `references/board.md`, `references/plan.md`.

package/dist/skills-packet/sfora-board/references/board.md

@@ -0,0 +1,60 @@
+# The board in detail
+
+## Where cards live
+
+```bash
+sfora ls /projects/hq/board --agent claude-code
+sfora ls /projects/hq/board/03-in-progress --agent claude-code
+sfora tasks hq --json --agent claude-code
+```
+
+The four columns are fixed: `01-triage`, `02-todo`, `03-in-progress`, `04-done`. Their display names are Triage, To do, In progress and Done. A card's file is its number and title slug, such as `0012-fix-login.md`.
+
+## A card file
+
+```markdown
+---
+column: In progress
+status: active
+priority: high
+labels: [auth]
+assignees: [claude-code]
+blocked-by: [9]
+---
+
+# Fix login
+
+What's wrong, what done looks like, and links to the evidence.
+```
+
+- `column:` moves the card. Crossing into Done closes it; leaving Done reopens it.
+- `status:` is `drafted`, `active` or `closed`.
+- `priority:` is `none`, `low`, `medium`, `high` or `urgent`.
+- `assignees:` are member names. A name that matches nobody is dropped.
+- `blocked-by:` takes card numbers, not titles.
+- `sfora cat` on a card prints more frontmatter (id, number, dates). Putting it back unchanged is fine.
+
+## Moving a card
+
+1. `sfora cat` the card into a local file.
+2. Change only the `column:` line.
+3. `sfora put` it back to the path you read it from. sfora finds the card by its number, so the old column in the path is fine.
+
+```bash
+sfora cat /projects/hq/board/02-todo/<card-file>.md --agent claude-code > card.md
+sfora put /projects/hq/board/02-todo/<card-file>.md card.md --agent claude-code
+```
+
+To change just the description, edit one block instead (see sfora-write). A block edit never moves the card.
+
+```bash
+sfora blocks /projects/hq/board/03-in-progress/<card-file>.md --agent claude-code
+sfora put /projects/hq/board/03-in-progress/<card-file>.md --block <block-id> block.md --agent claude-code
+```
+
+## Keeping it moving
+
+- Pick up a card by moving it to In progress and assigning yourself, in one put.
+- Say what changed in the card's body as you go, so a human can follow without asking.
+- Close a card by moving it to Done. If it's no longer needed, say so in the body first.
+- Check the board after every change with `sfora tasks`.