sfora-cli 0.16.0 → 0.17.0

package/dist/local-core/skills.js

@@ -51,6 +51,99 @@ export function validateSkillBundle(bundle) {
     if (skillBundleHash(bundle.files) !== bundle.hash)
         throw new Error("Invalid skill bundle hash.");
 }
+/** The longest `description` a SKILL.md may carry (the Agent Skills format's limit). */
+export const SKILL_DESCRIPTION_MAX = 1024;
+/**
+ * The top-level scalar keys of a SKILL.md frontmatter block, or `null` when the
+ * file does not open with one. A deliberately small YAML reader: plain, quoted
+ * and block (`|`, `>`) scalars, plus indented continuation lines. Nested maps
+ * (`metadata:`) are skipped. It never throws; a value it cannot read is absent.
+ */
+export function readSkillFrontmatter(markdown) {
+    const m = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(markdown);
+    if (!m)
+        return null;
+    const lines = m[1].split(/\r?\n/);
+    const out = {};
+    for (let i = 0; i < lines.length; i++) {
+        const key = /^([A-Za-z_][\w-]*):(?:[ \t]+(.*))?$/.exec(lines[i]);
+        if (!key)
+            continue;
+        const given = (key[2] ?? "").trim();
+        const raw = /^["']/.test(given) ? given : given.replace(/[ \t]+#.*$/, "").trim();
+        const body = [];
+        while (i + 1 < lines.length && (/^[ \t]+\S/.test(lines[i + 1]) || (lines[i + 1].trim() === "" && /^[|>]/.test(raw))))
+            body.push(lines[++i]);
+        let value;
+        if (/^[|>][+-]?$/.test(raw)) {
+            const indent = Math.min(...body.filter(l => l.trim()).map(l => /^[ \t]*/.exec(l)[0].length));
+            const text = body.map(l => l.slice(Number.isFinite(indent) ? indent : 0));
+            value = raw.startsWith("|") ? text.join("\n") : text.map(l => l.trim()).join(" ").replace(/ {2,}/g, " ");
+        }
+        else if (!raw && body.length)
+            continue; // a nested map, not a scalar
+        else {
+            value = [raw, ...body.map(l => l.trim())].filter(Boolean).join(" ");
+            const q = /^(["'])([\s\S]*)\1$/.exec(value);
+            if (q)
+                value = q[1] === "'" ? q[2].replace(/''/g, "'") : q[2].replace(/\\"/g, '"');
+        }
+        out[key[1]] = value.trim();
+    }
+    return out;
+}
+/**
+ * What is wrong with a bundle's SKILL.md frontmatter, as sentences; empty when
+ * nothing is. `name` must be present and equal the folder name, `description`
+ * present, non-empty and at most {@link SKILL_DESCRIPTION_MAX} characters.
+ * Kept apart from {@link validateSkillBundle} on purpose: that one gates every
+ * read (scan, inventory, uninstall, cloud download), and many existing skills
+ * have no frontmatter at all. This one gates what Sfora itself publishes or
+ * ships: `skills push` and `skills packet install`.
+ */
+export function skillFrontmatterProblems(bundle) {
+    const file = bundle.files.find(f => f.path === "SKILL.md");
+    if (!file)
+        return ["A skill must contain SKILL.md."];
+    const fm = readSkillFrontmatter(Buffer.from(file.contentBase64, "base64").toString("utf8"));
+    if (!fm)
+        return [`${bundle.name}/SKILL.md has no frontmatter: open it with a --- block carrying name and description.`];
+    const problems = [];
+    if (!fm.name)
+        problems.push(`${bundle.name}/SKILL.md frontmatter has no name.`);
+    else if (fm.name !== bundle.name)
+        problems.push(`${bundle.name}/SKILL.md frontmatter name '${fm.name}' differs from its folder name '${bundle.name}'.`);
+    if (!fm.description)
+        problems.push(`${bundle.name}/SKILL.md frontmatter has no description.`);
+    else if (fm.description.length > SKILL_DESCRIPTION_MAX)
+        problems.push(`${bundle.name}/SKILL.md description is ${fm.description.length} characters; the limit is ${SKILL_DESCRIPTION_MAX}.`);
+    return problems;
+}
+/**
+ * Throws every {@link skillFrontmatterProblems} finding, followed by the exact
+ * block to write, with the folder name filled in: a skill that pushed fine
+ * before this check existed is fixed with one edit.
+ */
+export function validateSkillFrontmatter(bundle) {
+    const problems = skillFrontmatterProblems(bundle);
+    if (!problems.length)
+        return;
+    const file = bundle.files.find(f => f.path === "SKILL.md");
+    const hasBlock = !!file && readSkillFrontmatter(Buffer.from(file.contentBase64, "base64").toString("utf8")) !== null;
+    throw new Error([
+        ...problems,
+        hasBlock
+            ? `Its frontmatter block must carry these two fields (keep any others):`
+            : `Add this at the very top of ${bundle.name}/SKILL.md:`,
+        "",
+        ...(hasBlock ? [] : ["---"]),
+        `name: ${bundle.name}`,
+        `description: Use when <the situation this skill is for>. Skip when <when it is not>.`,
+        ...(hasBlock ? [] : ["---"]),
+        "",
+        `name must equal the folder name; description is one line of at most ${SKILL_DESCRIPTION_MAX} characters.`,
+    ].join("\n"));
+}
 export async function readSkillBundle(directory, name = basename(resolve(directory))) {
     validateSkillName(name);
     if ((await lstat(directory)).isSymbolicLink())

package/dist/mcp-description.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `bash` tool's description for a cloud workspace, shared by the npm stdio
+ * server (`sfora --mcp`) and the hosted one (the app's POST /mcp), which run
+ * the same shell (card #811: the two had drifted, and the hosted text taught a
+ * board column that does not exist). Only what persists differs: the stdio
+ * server keeps one shell, so cwd and env carry over; each hosted call is a
+ * fresh shell at `/`.
+ */
+export declare function cloudToolDescription({ stateless }: {
+    stateless: boolean;
+}): string;

package/dist/mcp-description.js

@@ -0,0 +1,29 @@
+/**
+ * The `bash` tool's description for a cloud workspace, shared by the npm stdio
+ * server (`sfora --mcp`) and the hosted one (the app's POST /mcp), which run
+ * the same shell (card #811: the two had drifted, and the hosted text taught a
+ * board column that does not exist). Only what persists differs: the stdio
+ * server keeps one shell, so cwd and env carry over; each hosted call is a
+ * fresh shell at `/`.
+ */
+export function cloudToolDescription({ stateless }) {
+    const persistence = stateless
+        ? "Calls are stateless — always use absolute paths."
+        : "cwd and environment persist across calls.";
+    return `Run a bash command against the sfora workspace — a Unix-style view where every post, task, and doc is a markdown file:
+  - /projects/<slug>/posts/<file>.md            published posts
+  - /projects/<slug>/drafts/<file>.md           your drafts
+  - /projects/<slug>/board/<NN-stage>/<NNNN>.md tasks (kanban cards), by stage
+  - /projects/<slug>/library/documents/<file>.md workspace documents (writable)
+  - /projects/<slug>/library/files/<file>        uploaded files (read-only)
+  - /projects/<slug>/library/repositories/<repo> project source trees (read-only)
+  - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
+  - /projects/<slug>/plan.md                    the goal + open questions (write to set the goal)
+  - /projects/<slug>/asks.md                    coordination asks, read-only
+  - /inbox/mentions.md                          unread mentions
+  - /me/api-key                                 your identity
+Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; move a card into 04-done to close it. Question cards (kind: question) map their stage to the plan: triage = fuzzy, todo = up for grabs, in-progress = claimed, done = decided.
+Examples: 'ls /projects', 'cat /projects/web/board/02-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/02-todo/fix.md', 'mv /projects/web/board/02-todo/0003-*.md /projects/web/board/04-done/'.
+Write a file to create or update the entity (frontmatter sets fields like status/priority/assignees/due). ${persistence}
+Chat: 'typing <room> [--for <secs>]' shows the room you are working on a reply (agents; 30s by default, run again to extend); it ends when you send there, or with 'typing <room> --stop'.`;
+}

package/dist/mcp-server.d.ts

@@ -1,5 +1,7 @@
 /**
- * MCP stdio server exposing a single `bash` tool. Each tool call runs the
+ * MCP stdio server exposing a `bash` tool — plus, against the cloud, the
+ * `attachments` list and `attachment` fetch (card #822), which return a post's
+ * images as image content a vision client can see. Each bash call runs the
  * command through one persistent {@link createSforaShell} instance, with cwd/env
  * carried across calls (just-bash doesn't persist them itself), so an agent's
  * `cd` and `export` survive between tool invocations.
@@ -15,4 +17,6 @@ export interface RunMcpServerOptions {
     /** Terminal client slug for write attribution (`X-Sfora-Client`). */
     clientLabel?: string;
 }
+/** The shell the server runs commands in. Exported for the transport-header test (card #815). */
+export declare function createMcpShell(options: RunMcpServerOptions): import("./index.js").SforaShell | import("./index.js").LocalShell;
 export declare function runMcpServer(options: RunMcpServerOptions): Promise<void>;

package/dist/mcp-server.js

@@ -1,5 +1,7 @@
 /**
- * MCP stdio server exposing a single `bash` tool. Each tool call runs the
+ * MCP stdio server exposing a `bash` tool — plus, against the cloud, the
+ * `attachments` list and `attachment` fetch (card #822), which return a post's
+ * images as image content a vision client can see. Each bash call runs the
  * command through one persistent {@link createSforaShell} instance, with cwd/env
  * carried across calls (just-bash doesn't persist them itself), so an agent's
  * `cd` and `export` survive between tool invocations.
@@ -10,21 +12,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { createSforaShell, createLocalShell } from "./index.js";
-const TOOL_DESCRIPTION = `Run a bash command against the sfora workspace — a Unix-style view where every post, task, and doc is a markdown file:
-  - /projects/<slug>/posts/<file>.md            published posts
-  - /projects/<slug>/drafts/<file>.md           your drafts
-  - /projects/<slug>/board/<NN-stage>/<NNNN>.md tasks (kanban cards), by stage
-  - /projects/<slug>/library/documents/<file>.md workspace documents (writable)
-  - /projects/<slug>/library/files/<file>        uploaded files (read-only)
-  - /projects/<slug>/library/repositories/<repo> project source trees (read-only)
-  - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
-  - /projects/<slug>/plan.md                    the goal + open questions (write to set the goal)
-  - /projects/<slug>/asks.md                    coordination asks, read-only
-  - /inbox/mentions.md                          unread mentions
-  - /me/api-key                                 your identity
-Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; move a card into 04-done to close it. Question cards (kind: question) map their stage to the plan: triage = fuzzy, todo = up for grabs, in-progress = claimed, done = decided.
-Examples: 'ls /projects', 'cat /projects/web/board/02-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/02-todo/fix.md', 'mv /projects/web/board/02-todo/0003-*.md /projects/web/board/04-done/'.
-Write a file to create or update the entity (frontmatter sets fields like status/priority/assignees/due). cwd and environment persist across calls.`;
+import { ATTACHMENT_TOOLS, attachmentToolResult, isAttachmentTool } from "./attachments.js";
+import { cloudToolDescription } from "./mcp-description.js";
+// The cloud description is shared with the hosted /mcp route (card #811).
+const TOOL_DESCRIPTION = cloudToolDescription({ stateless: false });
 const LOCAL_TOOL_DESCRIPTION = `Run a bash command against the local sfora workspace (a .sfora/ directory of plain markdown files, git-versioned with the repo):
   - /board/<NN-stage>/<NNNN>-<slug>.md tasks (kanban cards), by stage — 'mv' between stage dirs moves a task
   - /posts/<YYYY-MM-DD>-<slug>.md      posts
@@ -32,15 +23,25 @@ const LOCAL_TOOL_DESCRIPTION = `Run a bash command against the local sfora works
 Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; moving a card into 04-done marks it done.
 Examples: 'ls /board/02-todo', 'cat /board/02-todo/*.md', 'grep -ri TODO /', 'echo "# Fix login\\nstatus: active" > /board/02-todo/fix-login.md', 'mv /board/02-todo/0003-*.md /board/04-done/'.
 Frontmatter sets task fields (status/priority/labels/assignees/due). cwd and environment persist across calls.`;
-export async function runMcpServer(options) {
-    const { bash } = options.localRoot
+/** The shell the server runs commands in. Exported for the transport-header test (card #815). */
+export function createMcpShell(options) {
+    return options.localRoot
         ? createLocalShell(options.localRoot)
         : createSforaShell({
             baseUrl: options.baseUrl,
             apiKey: options.apiKey,
             org: options.org,
             clientLabel: options.clientLabel,
+            // Card #815 (D11): this server's calls are MCP, not terminal commands.
+            transport: "mcp",
         });
+}
+export async function runMcpServer(options) {
+    // A local workspace has no attachments, so only the cloud shell's client
+    // answers the attachment tools.
+    const shell = createMcpShell(options);
+    const { bash } = shell;
+    const client = "client" in shell ? shell.client : null;
     // Persistent shell state across tool calls.
     let cwd = "/";
     let env;
@@ -61,9 +62,18 @@ export async function runMcpServer(options) {
                     required: ["command"],
                 },
             },
+            ...(client ? ATTACHMENT_TOOLS : []),
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (client && isAttachmentTool(request.params.name)) {
+            const args = (request.params.arguments ?? {});
+            return attachmentToolResult(client, {
+                path: args.path,
+                // `attachments` lists; only `attachment` fetches by id.
+                id: request.params.name === "attachment" ? (args.id ?? "") : undefined,
+            });
+        }
         if (request.params.name !== "bash") {
             return {
                 content: [

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-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 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";
+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,6 +1,7 @@
 import { dirname, join } from "node:path";
 import { readFile, realpath } from "node:fs/promises";
-import { diffSkillBundles, installSkillBundle, inspectSkillTarget, readSkillBundle, discoverSkills, SkillService, uninstallSkill, validateSkillBundle } from "./local-core/index.js";
+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";
@@ -35,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;
@@ -172,6 +177,18 @@ export async function runSkillsCommand(args, settings) {
         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);
@@ -194,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`.

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

@@ -0,0 +1,25 @@
+# The plan
+
+Each project has `/projects/<project>/plan.md`: the goal, what's decided, what's still open and what's in flight. sfora builds most of it from the board. You write one section: `## the goal`.
+
+```bash
+sfora cat /projects/hq/plan.md --agent claude-code > plan.md
+sfora put /projects/hq/plan.md plan.md --agent claude-code
+```
+
+## Writing the goal
+
+- Edit only the text under `## the goal`, up to the next heading.
+- Keep it to what the project is for and how you'll know it's done: two to four sentences.
+- Putting the whole file back is fine. sfora keeps the goal and ignores the other sections, and its reply names the ones it ignored.
+- An empty goal (or the italic "not set" placeholder) clears it.
+
+```markdown
+## the goal
+
+Ship the new sign-up flow to every Northfold customer by the end of the month. Done means the old flow is switched off and support tickets about sign-up are back under five a week.
+```
+
+## Questions in the plan
+
+Open questions are board cards with `kind: question` in their frontmatter. Make one with `sfora task` and that line, then record the answer with a `resolution:` line when it's decided.