sfora-cli 0.15.0 → 0.16.0

package/dist/local-core/skill-sync.d.ts

@@ -0,0 +1,132 @@
+import type { SkillCloudBinding, SkillRevision } from './skill-domain.js';
+import type { SkillStore } from './skill-store.js';
+import { type SkillBundle, type inspectSkillTarget } from './skills.js';
+export interface SkillCloudScope {
+    deployment: string;
+    accountId: string;
+    organizationId: string;
+}
+export interface PublishedSkillSnapshot {
+    remote: SkillCloudBinding['remote'];
+    accountId: string;
+    locator: SkillCloudBinding['locator'];
+    revision: SkillRevision;
+    draftRevision: number;
+    hasDraft: boolean;
+    draftHash?: string;
+    supportsIdentityGuards?: boolean;
+    bundle: SkillBundle;
+}
+export type SkillTransferPlan = ReturnType<typeof planSkillTransfer>;
+/** A new installation needs an explicitly selected empty destination, not a guessed name match. */
+export declare function planSkillInstallation(remote: PublishedSkillSnapshot, destination: string, target: Awaited<ReturnType<typeof inspectSkillTarget>>): {
+    schemaVersion: 1;
+    kind: "skill-install-preview";
+    source: {
+        accountId: string;
+        deployment: string;
+        organizationId: string;
+        skillId: string;
+        projectId: string;
+    };
+    locator: {
+        project: string;
+        name: string;
+    };
+    destination: string;
+    expected: {
+        remote: {
+            hash: string;
+            contentPolicy: "bundle-v1";
+            cloudVersion?: number;
+        };
+        targetState: "file" | "link" | "unavailable" | "managed" | "unmanaged" | "modified" | "missing";
+        localHash: string | null;
+    };
+    ownership: "unknown" | "managed" | "unmanaged";
+    outcome: string;
+    blockers: string[];
+    files: {
+        path: string;
+        kind: "added";
+        after: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        };
+    }[];
+};
+export type SkillContentState = {
+    state: 'available';
+    bundle: SkillBundle;
+} | {
+    state: 'missing';
+    reason: string;
+} | {
+    state: 'unavailable';
+    reason: string;
+};
+export type SkillSyncStatus = 'local-only' | 'synced' | 'local-changed' | 'remote-changed' | 'conflict' | 'missing' | 'unknown' | 'unavailable';
+export declare function assertSkillBindingScope(binding: SkillCloudBinding, scope: SkillCloudScope): void;
+export declare function validatePublishedSkillSnapshot(snapshot: PublishedSkillSnapshot): void;
+export declare function assertSkillBindingSnapshot(binding: SkillCloudBinding, snapshot: PublishedSkillSnapshot): void;
+/** Adoption is explicit. Matching names, install receipts and stale observations cannot establish a baseline. */
+export declare class SkillBindingService {
+    readonly store: SkillStore;
+    constructor(store: SkillStore);
+    list(): Promise<SkillCloudBinding[]>;
+    adopt(localSkillId: string, snapshot: PublishedSkillSnapshot, verifiedLocal: SkillBundle): Promise<SkillCloudBinding>;
+}
+/** Pure three-way comparison. Unavailable input is never interpreted as deletion or synchronization. */
+export declare function compareSkillStates(local: SkillContentState, remote: SkillContentState | undefined, baseline?: SkillRevision): SkillSyncStatus;
+/** Review artifact only. A future executor must revalidate every token and record a durable operation. */
+export declare function planSkillTransfer(input: {
+    direction: 'push' | 'pull';
+    binding: SkillCloudBinding;
+    location: {
+        id: string;
+        path: string;
+        skillId: string;
+    };
+    local: SkillContentState;
+    remote: PublishedSkillSnapshot;
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+}): {
+    schemaVersion: 1;
+    kind: "skill-transfer-preview";
+    direction: "push" | "pull";
+    status: SkillSyncStatus;
+    outcome: string;
+    blockers: string[];
+    binding: SkillCloudBinding;
+    location: {
+        id: string;
+        path: string;
+        skillId: string;
+    };
+    ownership: "unknown" | "managed" | "unmanaged";
+    expected: {
+        localHash: string | null;
+        remote: {
+            hash: string;
+            contentPolicy: "bundle-v1";
+            cloudVersion?: number;
+        };
+        draftRevision: number;
+    };
+    files: {
+        before: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        } | null;
+        after: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        } | null;
+        path: string;
+        kind: "added" | "removed" | "modified";
+    }[];
+};
+export type SkillInstallPlan = ReturnType<typeof planSkillInstallation>;

package/dist/local-core/skill-sync.js

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { diffSkillBundles, validateSkillBundle } from './skills.js';
+/** A new installation needs an explicitly selected empty destination, not a guessed name match. */
+export function planSkillInstallation(remote, destination, target) {
+    validatePublishedSkillSnapshot(remote);
+    if (!isAbsolute(destination))
+        throw new Error('Installation destination must be absolute.');
+    const blockers = target.state === 'missing' ? [] : ['Destination is occupied or unavailable. Choose a new folder, or explicitly bind and review an update.'];
+    return { schemaVersion: 1, kind: 'skill-install-preview', source: { ...remote.remote, accountId: remote.accountId }, locator: { ...remote.locator }, destination,
+        expected: { remote: { ...remote.revision }, targetState: target.state, localHash: target.hash ?? null }, ownership: target.ownership,
+        outcome: blockers.length ? 'blocked' : 'reviewable', blockers,
+        files: remote.bundle.files.map(f => ({ path: f.path, kind: 'added', after: { hash: f.sha256, size: f.size, executable: f.executable } })) };
+}
+export function assertSkillBindingScope(binding, scope) {
+    if (binding.accountId !== scope.accountId || binding.remote.deployment !== scope.deployment || binding.remote.organizationId !== scope.organizationId) {
+        throw new Error('Skill binding belongs to a different account, organization or deployment. Explicitly link the intended destination.');
+    }
+}
+export function validatePublishedSkillSnapshot(snapshot) {
+    validateSkillBundle(snapshot.bundle);
+    if (snapshot.revision.contentPolicy !== 'bundle-v1' || snapshot.revision.hash !== snapshot.bundle.hash
+        || !Number.isSafeInteger(snapshot.revision.cloudVersion) || Number(snapshot.revision.cloudVersion) < 1
+        || !Number.isSafeInteger(snapshot.draftRevision) || snapshot.draftRevision < 0 || typeof snapshot.hasDraft !== 'boolean') {
+        throw new Error('Published skill revision does not match its verified bundle.');
+    }
+}
+export function assertSkillBindingSnapshot(binding, snapshot) {
+    validatePublishedSkillSnapshot(snapshot);
+    assertSkillBindingScope(binding, { ...snapshot.remote, accountId: snapshot.accountId });
+    if (binding.remote.skillId !== snapshot.remote.skillId || binding.remote.projectId !== snapshot.remote.projectId) {
+        throw new Error('Cloud lookup resolved to a different skill identity. No binding was changed.');
+    }
+}
+/** Adoption is explicit. Matching names, install receipts and stale observations cannot establish a baseline. */
+export class SkillBindingService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async list() { return (await this.store.read()).bindings; }
+    async adopt(localSkillId, snapshot, verifiedLocal) {
+        validatePublishedSkillSnapshot(snapshot);
+        validateSkillBundle(verifiedLocal);
+        return this.store.transaction(c => {
+            if (!c.identities.some(i => i.id === localSkillId))
+                throw new Error('Local skill identity not found. Refresh the inventory first.');
+            const existing = c.bindings.find(b => b.localSkillId === localSkillId && b.accountId === snapshot.accountId
+                && b.remote.deployment === snapshot.remote.deployment && b.remote.organizationId === snapshot.remote.organizationId && b.remote.projectId === snapshot.remote.projectId);
+            if (existing)
+                assertSkillBindingSnapshot(existing, snapshot);
+            const binding = existing ?? { id: randomUUID(), localSkillId, remote: { ...snapshot.remote }, accountId: snapshot.accountId, locator: { ...snapshot.locator } };
+            binding.locator = { ...snapshot.locator };
+            // Differing bytes retain the last confirmed baseline, or remain unknown.
+            if (verifiedLocal.hash === snapshot.revision.hash)
+                binding.baseline = { ...snapshot.revision };
+            if (!existing)
+                c.bindings.push(binding);
+            return structuredClone(binding);
+        });
+    }
+}
+/** Pure three-way comparison. Unavailable input is never interpreted as deletion or synchronization. */
+export function compareSkillStates(local, remote, baseline) {
+    if (local.state === 'available')
+        validateSkillBundle(local.bundle);
+    if (remote?.state === 'available')
+        validateSkillBundle(remote.bundle);
+    if (local.state === 'unavailable' || remote?.state === 'unavailable')
+        return 'unavailable';
+    if (local.state === 'missing' || remote?.state === 'missing')
+        return 'missing';
+    if (!remote)
+        return 'local-only';
+    if (!baseline || baseline.contentPolicy !== 'bundle-v1' || !/^[a-f0-9]{64}$/.test(baseline.hash))
+        return 'unknown';
+    if (local.bundle.hash === remote.bundle.hash)
+        return 'synced';
+    if (local.bundle.hash === baseline.hash)
+        return 'remote-changed';
+    if (remote.bundle.hash === baseline.hash)
+        return 'local-changed';
+    return 'conflict';
+}
+/** Review artifact only. A future executor must revalidate every token and record a durable operation. */
+export function planSkillTransfer(input) {
+    const { binding, local, remote, direction, location, ownership } = input;
+    assertSkillBindingSnapshot(binding, remote);
+    if (location.skillId !== binding.localSkillId)
+        throw new Error('Location does not belong to the bound local skill.');
+    const status = compareSkillStates(local, { state: 'available', bundle: remote.bundle }, binding.baseline);
+    const blockers = [];
+    if (!['synced', direction === 'push' ? 'local-changed' : 'remote-changed'].includes(status))
+        blockers.push(`Cannot ${direction} automatically from ${status}; review the divergence first.`);
+    if (status !== 'synced' && direction === 'pull' && ownership !== 'managed')
+        blockers.push('Replacing local files requires verified Sfora ownership or an explicitly chosen new destination.');
+    if (status !== 'synced' && direction === 'push' && remote.hasDraft)
+        blockers.push('The cloud contains an unpublished draft; review it before replacing it.');
+    const before = direction === 'push' ? remote.bundle : local.state === 'available' ? local.bundle : undefined;
+    const after = direction === 'pull' ? remote.bundle : local.state === 'available' ? local.bundle : undefined;
+    const files = before && after ? diffSkillBundles(before, after).map(change => {
+        const metadata = (bundle) => { const f = bundle.files.find(f => f.path === change.path); return f ? { hash: f.sha256, size: f.size, executable: f.executable } : null; };
+        return { ...change, before: metadata(before), after: metadata(after) };
+    }) : [];
+    return {
+        schemaVersion: 1, kind: 'skill-transfer-preview', direction, status,
+        outcome: blockers.length ? 'blocked' : status === 'synced' ? 'no-op' : 'reviewable', blockers,
+        binding: structuredClone(binding), location: { ...location }, ownership,
+        expected: { localHash: local.state === 'available' ? local.bundle.hash : null, remote: { ...remote.revision }, draftRevision: remote.draftRevision }, files,
+    };
+}

package/dist/local-core/skills.d.ts

@@ -34,6 +34,7 @@ export declare function validateSkillPath(path: string): void;
 export declare function skillBundleHash(files: SkillFile[]): string;
 export declare function validateSkillBundle(bundle: SkillBundle): void;
 export declare function readSkillBundle(directory: string, name?: string): Promise<SkillBundle>;
+/** Legacy array API; the shared discovery engine owns all traversal. */
 export declare function scanLocalSkills(roots?: string[]): Promise<Array<{
     path: string;
     name: string;
@@ -41,5 +42,14 @@ export declare function scanLocalSkills(roots?: string[]): Promise<Array<{
     error?: string;
 }>>;
 export declare function diffSkillBundles(local: SkillBundle, incoming: SkillBundle): SkillDifference[];
+export declare function readInstallation(destination: string): Promise<SkillInstallation | undefined>;
+/** A receipt is historical intent. Classify today's filesystem object before trusting it. */
+export declare function inspectSkillTarget(directory: string): Promise<{
+    state: 'missing' | 'link' | 'file' | 'managed' | 'modified' | 'unmanaged' | 'unavailable';
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+    hash?: string;
+    receipt?: SkillInstallation;
+    reason?: string;
+}>;
 export declare function installSkillBundle(bundle: SkillBundle, targetRoot: string, source?: string, sourceVersion?: number): Promise<SkillInstallation>;
 export declare function uninstallSkill(directory: string): Promise<void>;

package/dist/local-core/skills.js

@@ -1,7 +1,6 @@
 import { constants } from "node:fs";
-import { chmod, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { atomicWrite, LocalConflictError, sha256, withLocalLock } from "./files.js";
 export const SKILL_LIMITS = { files: 1000, fileBytes: 5 * 1024 * 1024, totalBytes: 20 * 1024 * 1024 };
@@ -99,38 +98,13 @@ export async function readSkillBundle(directory, name = basename(resolve(directo
     validateSkillBundle(bundle);
     return bundle;
 }
-export async function scanLocalSkills(roots = [join(homedir(), ".agents/skills"), join(homedir(), ".codex/skills"), join(homedir(), ".claude/skills")]) {
-    const results = [];
-    for (const root of roots) {
-        let entries;
-        try {
-            entries = await readdir(root, { withFileTypes: true });
-        }
-        catch (e) {
-            if (e.code === "ENOENT")
-                continue;
-            throw e;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith("."))
-                continue;
-            const path = join(root, entry.name);
-            try {
-                await lstat(join(path, "SKILL.md"));
-            }
-            catch {
-                continue;
-            }
-            try {
-                const bundle = await readSkillBundle(path);
-                results.push({ path, name: bundle.name, hash: bundle.hash });
-            }
-            catch (e) {
-                results.push({ path, name: entry.name, error: e instanceof Error ? e.message : String(e) });
-            }
-        }
-    }
-    return results;
+/** Legacy array API; the shared discovery engine owns all traversal. */
+export async function scanLocalSkills(roots) {
+    const { discoverSkills } = await import("./skill-discovery.js");
+    const result = await discoverSkills(roots?.map(path => ({ path, label: "Chosen folder", depth: 4 })));
+    if (result.warnings.length)
+        throw new Error(result.warnings.join("\n"));
+    return result.skills;
 }
 export function diffSkillBundles(local, incoming) {
     validateSkillBundle(local);
@@ -147,10 +121,24 @@ export function diffSkillBundles(local, incoming) {
     });
 }
 function recordPath(destination) { return join(dirname(destination), `.${basename(destination)}.sfora-install.json`); }
-async function readInstallation(destination) {
+export async function readInstallation(destination) {
     try {
-        const record = JSON.parse(await readFile(recordPath(destination), "utf8"));
-        if (record.schemaVersion !== 1 || record.path !== destination)
+        const handle = await open(recordPath(destination), constants.O_RDONLY | constants.O_NOFOLLOW);
+        let raw;
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65536)
+                throw new Error('Invalid installation record file.');
+            raw = await handle.readFile('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        const record = JSON.parse(raw);
+        if (record.schemaVersion !== 1 || record.path !== destination || record.name !== basename(destination)
+            || !/^[a-f0-9]{64}$/.test(record.hash) || !Number.isSafeInteger(record.installedAt) || record.installedAt < 0
+            || (record.source !== undefined && (typeof record.source !== 'string' || record.source.length > 8192))
+            || (record.sourceVersion !== undefined && (!Number.isSafeInteger(record.sourceVersion) || record.sourceVersion < 1)))
             throw new Error("Unsupported or mismatched installation record.");
         return record;
     }
@@ -160,6 +148,30 @@ async function readInstallation(destination) {
         throw e;
     }
 }
+/** A receipt is historical intent. Classify today's filesystem object before trusting it. */
+export async function inspectSkillTarget(directory) {
+    try {
+        const destination = join(await realpath(dirname(resolve(directory))), basename(directory));
+        const info = await lstat(destination).catch(e => { if (e.code === 'ENOENT')
+            return null; throw e; });
+        if (!info)
+            return { state: 'missing', ownership: 'unknown' };
+        if (info.isSymbolicLink())
+            return { state: 'link', ownership: 'unmanaged', reason: 'A link cannot be replaced using a copy installation receipt.' };
+        if (!info.isDirectory())
+            return { state: 'file', ownership: 'unmanaged', reason: 'The target is no longer a skill directory.' };
+        const bundle = await readSkillBundle(destination);
+        const receipt = await readInstallation(destination);
+        if (!receipt)
+            return { state: 'unmanaged', ownership: 'unmanaged', hash: bundle.hash };
+        if (receipt.hash !== bundle.hash)
+            return { state: 'modified', ownership: 'unmanaged', hash: bundle.hash, receipt, reason: 'The managed copy has local changes.' };
+        return { state: 'managed', ownership: 'managed', hash: bundle.hash, receipt };
+    }
+    catch (error) {
+        return { state: 'unavailable', ownership: 'unknown', reason: error.message };
+    }
+}
 export async function installSkillBundle(bundle, targetRoot, source, sourceVersion) {
     validateSkillBundle(bundle);
     if (sourceVersion !== undefined && (!Number.isSafeInteger(sourceVersion) || sourceVersion < 1))

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";
 export declare function runSkillsCommand(args: CliArgs, settings: ResolvedSettings): Promise<void>;