@rynx-ai/cli 0.1.10 → 0.1.11-beta.2

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-export { callManagedRuntimeBrowser, callResidentRuntime, cancelResidentPluginInstallation, commitResidentPluginInstallation, cleanResidentBrowserArtifacts, cleanupResidentSessions, createResidentRemoteRuntimePairingOffer, ensureResidentDaemon, forgetResidentRuntimeTarget, getResidentChromeInspectionStatus, getResidentDaemonIdentity, getResidentDaemonRuntimeStatus, getResidentBrowserArtifactVersion, getResidentRuntimeLocalBrowserEndpoint, invokeResidentPluginCommand, installResidentBrowserArtifact, listResidentPlugins, listResidentRemoteRuntimeClients, listResidentRuntimeTargets, pairResidentRuntimeTarget, prepareResidentPluginInstallation, readManagedRuntimeBrowserCredential, readOptionalManagedRuntimeBrowserCredential, reloadResidentPluginRuntime, revokeResidentRemoteRuntimeClient, setResidentPluginEnabled, shutdownResidentDaemonIfIdle, configureResidentChromeInspection, testResidentRuntimeTarget, uninstallResidentPlugin, updateResidentBrowserArtifact, connectResidentDesktopBrowserHost, ResidentRuntimeCallError, type InvokeResidentPluginCommandOptions, type ResidentDaemon, type ResidentDaemonIdentity, type ResidentDesktopBrowserHostCommandRequest, type ResidentDesktopBrowserHostConnectOptions, type ResidentDesktopBrowserHostConnection, type ResidentDesktopBrowserHostFailure, type ResidentPluginCommandResult, type ResidentPluginManagementItem, type ResidentPluginManagementState, type ResidentRemoteRuntimeClientGrant, type ResidentRuntimeCallErrorCode, type ResidentRuntimeCallOutcome, type ResidentRuntimeTargetTestResult, type ResidentRuntimeTargetView, } from "./control-client.js";
+export { callManagedRuntimeBrowser, callResidentRuntime, cancelResidentPluginInstallation, commitResidentPluginInstallation, cleanResidentBrowserArtifacts, cleanupResidentSessions, createResidentRemoteRuntimePairingOffer, ensureResidentDaemon, forgetResidentRuntimeTarget, getResidentChromeInspectionStatus, getResidentDaemonIdentity, getResidentDaemonRuntimeStatus, getResidentBrowserArtifactVersion, getResidentRuntimeLocalBrowserEndpoint, invokeResidentPluginCommand, installResidentBrowserArtifact, listResidentPlugins, listResidentRemoteRuntimeClients, listResidentRuntimeTargets, pairResidentRuntimeTarget, prepareResidentPluginInstallation, readManagedRuntimeBrowserCredential, readOptionalManagedRuntimeBrowserCredential, revokeResidentRemoteRuntimeClient, setResidentPluginEnabled, shutdownResidentDaemonIfIdle, configureResidentChromeInspection, testResidentRuntimeTarget, uninstallResidentPlugin, updateResidentBrowserArtifact, connectResidentDesktopBrowserHost, ResidentRuntimeCallError, type InvokeResidentPluginCommandOptions, type ResidentDaemon, type ResidentDaemonIdentity, type ResidentDesktopBrowserHostCommandRequest, type ResidentDesktopBrowserHostConnectOptions, type ResidentDesktopBrowserHostConnection, type ResidentDesktopBrowserHostFailure, type ResidentPluginCommandResult, type ResidentPluginManagementItem, type ResidentPluginManagementState, type ResidentRemoteRuntimeClientGrant, type ResidentRuntimeCallErrorCode, type ResidentRuntimeCallOutcome, type ResidentRuntimeTargetTestResult, type ResidentRuntimeTargetView, } from "./control-client.js";
 export type { DaemonChromeInspectionConfigureInput, DaemonChromeInspectionStatus, } from "@rynx-ai/protocol/control";
 export type { PluginInstallCommitInput, PluginInstallCommitResult, PluginInstallPreparation, PluginInstallPrepareInput, } from "@rynx-ai/protocol/plugin-management";
 export { ensureDaemonControlEndpoint, resolveDaemonControlEndpoint, type DaemonControlEndpoint, type ResolveDaemonControlEndpointOptions, } from "./control-endpoint.js";

package/dist/client.js

@@ -1,2 +1,2 @@
-export { callManagedRuntimeBrowser, callResidentRuntime, cancelResidentPluginInstallation, commitResidentPluginInstallation, cleanResidentBrowserArtifacts, cleanupResidentSessions, createResidentRemoteRuntimePairingOffer, ensureResidentDaemon, forgetResidentRuntimeTarget, getResidentChromeInspectionStatus, getResidentDaemonIdentity, getResidentDaemonRuntimeStatus, getResidentBrowserArtifactVersion, getResidentRuntimeLocalBrowserEndpoint, invokeResidentPluginCommand, installResidentBrowserArtifact, listResidentPlugins, listResidentRemoteRuntimeClients, listResidentRuntimeTargets, pairResidentRuntimeTarget, prepareResidentPluginInstallation, readManagedRuntimeBrowserCredential, readOptionalManagedRuntimeBrowserCredential, reloadResidentPluginRuntime, revokeResidentRemoteRuntimeClient, setResidentPluginEnabled, shutdownResidentDaemonIfIdle, configureResidentChromeInspection, testResidentRuntimeTarget, uninstallResidentPlugin, updateResidentBrowserArtifact, connectResidentDesktopBrowserHost, ResidentRuntimeCallError, } from "./control-client.js";
+export { callManagedRuntimeBrowser, callResidentRuntime, cancelResidentPluginInstallation, commitResidentPluginInstallation, cleanResidentBrowserArtifacts, cleanupResidentSessions, createResidentRemoteRuntimePairingOffer, ensureResidentDaemon, forgetResidentRuntimeTarget, getResidentChromeInspectionStatus, getResidentDaemonIdentity, getResidentDaemonRuntimeStatus, getResidentBrowserArtifactVersion, getResidentRuntimeLocalBrowserEndpoint, invokeResidentPluginCommand, installResidentBrowserArtifact, listResidentPlugins, listResidentRemoteRuntimeClients, listResidentRuntimeTargets, pairResidentRuntimeTarget, prepareResidentPluginInstallation, readManagedRuntimeBrowserCredential, readOptionalManagedRuntimeBrowserCredential, revokeResidentRemoteRuntimeClient, setResidentPluginEnabled, shutdownResidentDaemonIfIdle, configureResidentChromeInspection, testResidentRuntimeTarget, uninstallResidentPlugin, updateResidentBrowserArtifact, connectResidentDesktopBrowserHost, ResidentRuntimeCallError, } from "./control-client.js";
 export { ensureDaemonControlEndpoint, resolveDaemonControlEndpoint, } from "./control-endpoint.js";

package/dist/commands/index.d.ts

@@ -5,5 +5,7 @@ export { runCleanupCommand } from "./cleanup.js";
 export { runEmulatorCommand } from "./emulator.js";
 export { CliUsageError } from "./errors.js";
 export { type PluginManageCommandOptions, runPluginCommand, runPluginManageCommand, } from "./plugin.js";
+export { runMarketCommand } from "./market.js";
 export { runRuntimeCommand } from "./runtime.js";
-export { builtinSkillsDirectory, listBuiltinSkills, readBuiltinSkill, runSkillsCommand, } from "./skills.js";
+export { runSessionCommand } from "./session.js";
+export { builtinSkillGuidesDirectory, listBuiltinSkills, readBuiltinSkill, runSkillsCommand, } from "./skills.js";

package/dist/commands/index.js

@@ -5,5 +5,7 @@ export { runCleanupCommand } from "./cleanup.js";
 export { runEmulatorCommand } from "./emulator.js";
 export { CliUsageError } from "./errors.js";
 export { runPluginCommand, runPluginManageCommand, } from "./plugin.js";
+export { runMarketCommand } from "./market.js";
 export { runRuntimeCommand } from "./runtime.js";
-export { builtinSkillsDirectory, listBuiltinSkills, readBuiltinSkill, runSkillsCommand, } from "./skills.js";
+export { runSessionCommand } from "./session.js";
+export { builtinSkillGuidesDirectory, listBuiltinSkills, readBuiltinSkill, runSkillsCommand, } from "./skills.js";

package/dist/commands/market.d.ts

@@ -0,0 +1 @@
+export declare function runMarketCommand(args: readonly string[]): Promise<number>;

package/dist/commands/market.js

@@ -0,0 +1,71 @@
+import { addResidentPluginMarketplace, listResidentPluginMarketplaces, refreshResidentPluginMarketplace, removeResidentPluginMarketplace, } from "../control-client.js";
+import { fail } from "./errors.js";
+export async function runMarketCommand(args) {
+    const [command, target, ...rest] = args;
+    switch (command) {
+        case "list": {
+            rejectExtra(rest, "market list");
+            const markets = await listResidentPluginMarketplaces();
+            console.log("Markets");
+            if (markets.length === 0) {
+                console.log("  (none)");
+                return 0;
+            }
+            for (const market of markets) {
+                const source = market.builtIn ? "built-in" : market.source;
+                const revision = market.builtIn ? "bundled with Rynx" : market.resolvedRevision;
+                console.log(`  ${market.id.padEnd(24)} ${source.padEnd(8)} ` +
+                    `${String(market.plugins.length).padStart(3)} plugins  ${revision}`);
+            }
+            return 0;
+        }
+        case "add": {
+            if (!target || target.startsWith("--"))
+                fail("market add: missing Git/local source");
+            let alias;
+            for (let index = 0; index < rest.length; index += 1) {
+                const arg = rest[index];
+                if (arg !== "--alias" || alias !== undefined)
+                    fail(`market add: unexpected option ${arg}`);
+                const value = rest[index + 1];
+                if (!value || value.startsWith("--"))
+                    fail("market add: --alias requires a value");
+                alias = value;
+                index += 1;
+            }
+            const market = await addResidentPluginMarketplace({
+                source: target,
+                ...(alias ? { alias } : {}),
+            });
+            console.log(`Market "${market.id}" added with ${market.plugins.length} plugin(s).`);
+            return 0;
+        }
+        case "refresh": {
+            rejectExtra(rest, "market refresh");
+            const ids = target
+                ? [target]
+                : (await listResidentPluginMarketplaces()).map((market) => market.id);
+            for (const id of ids) {
+                const market = await refreshResidentPluginMarketplace(id);
+                console.log(`Market "${market.id}" refreshed at ${market.resolvedRevision}.`);
+            }
+            if (ids.length === 0)
+                console.log("No Markets to refresh.");
+            return 0;
+        }
+        case "remove": {
+            if (!target)
+                fail("market remove: missing market id");
+            rejectExtra(rest, "market remove");
+            await removeResidentPluginMarketplace(target);
+            console.log(`Market "${target}" removed.`);
+            return 0;
+        }
+        default:
+            fail("market: expected list, add, refresh, or remove");
+    }
+}
+function rejectExtra(args, command) {
+    if (args.length > 0)
+        fail(`${command}: unexpected argument ${args[0]}`);
+}

package/dist/commands/plugin.js

@@ -1,8 +1,9 @@
 import { createInterface } from "node:readline/promises";
-import { cancelResidentPluginInstallation, commitResidentPluginInstallation, invokeResidentPluginCommand, listResidentPlugins, prepareResidentPluginInstallation, reloadResidentPluginRuntime, setResidentPluginEnabled, uninstallResidentPlugin, } from "../control-client.js";
+import { cancelResidentPluginInstallation, commitResidentPluginInstallation, invokeResidentPluginCommand, listResidentPlugins, prepareResidentPluginInstallation, setResidentPluginEnabled, uninstallResidentPlugin, } from "../control-client.js";
 import { fail } from "./errors.js";
 const PLUGIN_STDIN_MAX_BYTES = 256 * 1024;
 const PLUGIN_DIGEST_PATTERN = /^sha256-[A-Za-z0-9+/]{43}={0,2}$/;
+const CANONICAL_PLUGIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,62}@[a-z0-9][a-z0-9-]{0,62}(?:\/[a-z0-9][a-z0-9._-]{0,99})?$/;
 export async function runPluginManageCommand(args, options = {}) {
     const [subcommand, pluginId] = args;
     switch (subcommand) {
@@ -22,16 +23,16 @@ export async function runPluginManageCommand(args, options = {}) {
         case "enable":
         case "disable": {
             if (!pluginId)
-                fail(`plugin manage ${subcommand}: missing plugin id`);
+                fail(`plugin ${subcommand}: missing canonical plugin id`);
             await setResidentPluginEnabled(pluginId, subcommand === "enable");
-            console.log(`Plugin "${pluginId}" ${subcommand}d. Run \`rynx restart\` to apply.`);
+            console.log(`Plugin "${pluginId}" ${subcommand}d.`);
             return 0;
         }
         case "uninstall": {
             if (!pluginId)
-                fail("plugin manage uninstall: missing plugin id");
+                fail("plugin uninstall: missing canonical plugin id");
             await uninstallResidentPlugin(pluginId);
-            console.log(`Plugin "${pluginId}" uninstalled. Run \`rynx restart\` to apply.`);
+            console.log(`Plugin "${pluginId}" uninstalled.`);
             return 0;
         }
         case "install":
@@ -40,9 +41,10 @@ export async function runPluginManageCommand(args, options = {}) {
             const preparation = await prepareResidentPluginInstallation({
                 operation: subcommand,
                 ...(subcommand === "install"
-                    ? { spec: parsed.target }
+                    ? CANONICAL_PLUGIN_ID_PATTERN.test(parsed.target)
+                        ? { marketplacePlugin: parsed.target }
+                        : { spec: parsed.target }
                     : { pluginId: parsed.target }),
-                allowScripts: parsed.allowScripts,
             });
             let committed = false;
             try {
@@ -56,26 +58,24 @@ export async function runPluginManageCommand(args, options = {}) {
                     fail(`prepared plugin digest ${preparation.artifact.digest} does not match ` +
                         `--expect-digest ${parsed.expectedDigest}`);
                 }
+                if (subcommand === "update" && preparation.unchanged) {
+                    if (parsed.json) {
+                        console.log(JSON.stringify({
+                            preparation: publicPreparation(preparation),
+                            unchanged: true,
+                        }, null, 2));
+                    }
+                    else {
+                        console.log(`Plugin "${preparation.artifact.id}" is already up to date.`);
+                    }
+                    return 0;
+                }
                 if ((!interactive || parsed.json) &&
-                    (parsed.force || parsed.grantAll || parsed.allowScripts) &&
+                    parsed.force &&
                     parsed.expectedDigest === undefined) {
-                    fail("non-interactive --force/--grant-all/--allow-scripts approval must be bound to the " +
+                    fail("non-interactive --force confirmation must be bound to the " +
                         `prepared artifact; re-run with --expect-digest ${preparation.artifact.digest}`);
                 }
-                if (preparation.artifact.requiresBuildScripts && !parsed.allowScripts) {
-                    fail(`plugin "${preparation.artifact.id}" requires package build scripts; ` +
-                        `review digest ${preparation.artifact.digest} and re-run with ` +
-                        `--allow-scripts --expect-digest ${preparation.artifact.digest}`);
-                }
-                if (preparation.artifact.requiresBuildScripts &&
-                    parsed.allowScripts &&
-                    parsed.expectedDigest === undefined) {
-                    const approved = await confirm(`Run declared build scripts from digest ${preparation.artifact.digest}?`);
-                    if (!approved) {
-                        console.log("Plugin installation cancelled; build scripts were not run.");
-                        return 0;
-                    }
-                }
                 let overwrite = subcommand === "update";
                 if (subcommand === "install" && preparation.existing) {
                     overwrite = parsed.force;
@@ -92,49 +92,15 @@ export async function runPluginManageCommand(args, options = {}) {
                         }
                     }
                 }
-                let grants = [...preparation.capabilityDiff.retained];
-                if (preparation.capabilityDiff.added.length > 0) {
-                    if (parsed.grantAll) {
-                        grants = [...preparation.artifact.requestedCapabilities];
-                    }
-                    else {
-                        if (!interactive || parsed.json) {
-                            fail(`plugin "${preparation.artifact.id}" requests new capabilities ` +
-                                `(${preparation.capabilityDiff.added.join(", ")}); inspect digest ` +
-                                `${preparation.artifact.digest} and re-run with ` +
-                                `--grant-all --expect-digest ${preparation.artifact.digest}`);
-                        }
-                        const approved = await confirm(`Grant ${preparation.capabilityDiff.added.length} new capability(s) ` +
-                            `to "${preparation.artifact.id}"?`);
-                        if (!approved) {
-                            console.log("Plugin installation cancelled; no changes were made.");
-                            return 0;
-                        }
-                        grants = [...preparation.artifact.requestedCapabilities];
-                    }
-                }
                 const result = await commitResidentPluginInstallation(preparation.token, {
-                    grants,
                     overwrite,
                     expectedDigest: preparation.artifact.digest,
                 });
                 committed = true;
-                let runtimeReloaded = false;
-                if (parsed.restart) {
-                    try {
-                        await reloadResidentPluginRuntime(result.plugin.id);
-                        runtimeReloaded = true;
-                    }
-                    catch (error) {
-                        throw new Error(`Plugin "${result.plugin.id}" was committed, but its runtime did not reload: ` +
-                            `${messageOf(error)}`, { cause: error });
-                    }
-                }
                 if (parsed.json) {
                     console.log(JSON.stringify({
                         preparation: publicPreparation(preparation),
                         plugin: result.plugin,
-                        runtimeReloaded,
                     }, null, 2));
                 }
                 else {
@@ -142,9 +108,7 @@ export async function runPluginManageCommand(args, options = {}) {
                     console.log(`Plugin "${result.plugin.id}"${result.plugin.version
                         ? ` @${result.plugin.version}`
                         : ""} ${action}.`);
-                    console.log(parsed.restart
-                        ? `Plugin "${result.plugin.id}" runtime is ready.`
-                        : "Use --restart to reload the plugin runtime now.");
+                    console.log(`Runtime state: ${result.plugin.runtimeState}.`);
                 }
                 return 0;
             }
@@ -155,15 +119,15 @@ export async function runPluginManageCommand(args, options = {}) {
             }
         }
         default:
-            fail("plugin manage: expected list, install, update, uninstall, enable, or disable");
+            fail("plugin: expected list, install, update, uninstall, enable, or disable");
     }
 }
 export async function runPluginCommand(args) {
     const [pluginId, command] = args;
     if (!pluginId)
         fail("plugin: missing plugin id");
-    if (pluginId === "manage") {
-        return runPluginManageCommand(args.slice(1));
+    if (["list", "install", "update", "uninstall", "enable", "disable"].includes(pluginId)) {
+        return runPluginManageCommand(args);
     }
     if (!command)
         fail(`plugin ${pluginId}: missing command`);
@@ -184,15 +148,12 @@ function parseInstallationArgs(operation, args) {
     const target = args[0];
     if (!target || target.startsWith("--")) {
         fail(operation === "install"
-            ? "plugin manage install: missing npm/path/git/url source"
-            : "plugin manage update: missing plugin id");
+            ? "plugin install: missing Git/local source or market plugin identity"
+            : "plugin update: missing canonical plugin id");
     }
     const flags = new Set();
     const allowedFlags = new Set([
         "--force",
-        "--grant-all",
-        "--allow-scripts",
-        "--restart",
         "--json",
     ]);
     let expectedDigest;
@@ -200,36 +161,33 @@ function parseInstallationArgs(operation, args) {
         const arg = args[index];
         if (arg === "--expect-digest" || arg === "--expected-digest") {
             if (expectedDigest !== undefined) {
-                fail(`plugin manage ${operation}: duplicate digest expectation`);
+                fail(`plugin ${operation}: duplicate digest expectation`);
             }
             const value = args[index + 1];
             if (!value || value.startsWith("--")) {
-                fail(`plugin manage ${operation}: ${arg} requires a value`);
+                fail(`plugin ${operation}: ${arg} requires a value`);
             }
             if (!PLUGIN_DIGEST_PATTERN.test(value)) {
-                fail(`plugin manage ${operation}: ${arg} must be a sha256 digest`);
+                fail(`plugin ${operation}: ${arg} must be a sha256 digest`);
             }
             expectedDigest = value;
             index += 1;
             continue;
         }
         if (!arg.startsWith("--")) {
-            fail(`plugin manage ${operation}: unexpected argument ${arg}`);
+            fail(`plugin ${operation}: unexpected argument ${arg}`);
         }
         if (!allowedFlags.has(arg)) {
-            fail(`plugin manage ${operation}: unknown option ${arg}`);
+            fail(`plugin ${operation}: unknown option ${arg}`);
         }
         if (flags.has(arg)) {
-            fail(`plugin manage ${operation}: duplicate option ${arg}`);
+            fail(`plugin ${operation}: duplicate option ${arg}`);
         }
         flags.add(arg);
     }
     return {
         target,
         force: flags.has("--force"),
-        grantAll: flags.has("--grant-all"),
-        allowScripts: flags.has("--allow-scripts"),
-        restart: flags.has("--restart"),
         json: flags.has("--json"),
         ...(expectedDigest ? { expectedDigest } : {}),
     };
@@ -240,19 +198,8 @@ function printPreparation(preparation) {
         : "";
     console.log(`Prepared plugin "${preparation.artifact.id}"${version}.`);
     console.log(`Artifact digest: ${preparation.artifact.digest}`);
-    if (preparation.artifact.requiresBuildScripts) {
-        console.log("Package build scripts: required and explicitly enabled.");
-    }
-    printCapabilities("New capabilities", preparation.capabilityDiff.added);
-    printCapabilities("Retained capabilities", preparation.capabilityDiff.retained);
-    printCapabilities("Removed capabilities", preparation.capabilityDiff.removed);
-}
-function printCapabilities(label, capabilities) {
-    if (capabilities.length === 0)
-        return;
-    console.log(`${label}:`);
-    for (const capability of capabilities)
-        console.log(`  - ${capability}`);
+    console.log(`Source: ${preparation.artifact.source}`);
+    console.log(`Runtime: ${preparation.artifact.hasRuntime ? "declared" : "none"}`);
 }
 function publicPreparation(preparation) {
     const { token: _token, ...publicFields } = preparation;
@@ -272,9 +219,6 @@ async function confirmInTerminal(message) {
         prompt.close();
     }
 }
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 async function readStdinBounded(maxBytes) {
     const chunks = [];
     let bytes = 0;

package/dist/commands/session.d.ts

@@ -0,0 +1 @@
+export declare function runSessionCommand(args: readonly string[]): Promise<number>;

package/dist/commands/session.js

@@ -0,0 +1,38 @@
+import { randomUUID } from "node:crypto";
+import { callResidentRuntime } from "../control-client.js";
+import { fail } from "./errors.js";
+export async function runSessionCommand(args) {
+    const [command, sourceSessionId, ...options] = args;
+    if (command !== "fork" || !sourceSessionId) {
+        fail("Usage: rynx session fork <session-id> [--title <title>] [--json]");
+    }
+    let title;
+    let json = false;
+    for (let index = 0; index < options.length; index += 1) {
+        const option = options[index];
+        if (option === "--json") {
+            if (json)
+                fail("session fork: duplicate option --json");
+            json = true;
+            continue;
+        }
+        if (option === "--title") {
+            if (title !== undefined)
+                fail("session fork: duplicate option --title");
+            title = options[++index];
+            if (!title?.trim())
+                fail("session fork: --title requires a value");
+            continue;
+        }
+        fail(`session fork: unknown option ${option}`);
+    }
+    const result = await callResidentRuntime("local", "session.fork", {
+        sourceSessionId,
+        operationId: `cli_${randomUUID()}`,
+        ...(title ? { title: title.trim() } : {}),
+    });
+    console.log(json
+        ? JSON.stringify(result)
+        : result.sessionId);
+    return 0;
+}

package/dist/commands/skills.d.ts

@@ -1,10 +1,12 @@
 export interface BuiltinSkill {
     name: string;
-    directory: string;
-    skillFile: string;
+    description: string;
     content: string;
+    full: boolean;
 }
 export declare function runSkillsCommand(args: readonly string[]): Promise<number>;
 export declare function listBuiltinSkills(): Promise<BuiltinSkill[]>;
-export declare function readBuiltinSkill(name: string): Promise<BuiltinSkill | null>;
-export declare function builtinSkillsDirectory(moduleUrl?: string, env?: NodeJS.ProcessEnv): string;
+export declare function readBuiltinSkill(name: string, full?: boolean): Promise<BuiltinSkill | null>;
+/** Resolve only inside the independently published @rynx-ai/cli package.
+ * The source and compiled module depths are identical (`src|dist/commands`). */
+export declare function builtinSkillGuidesDirectory(moduleUrl?: string): string;

package/dist/commands/skills.js

@@ -1,21 +1,26 @@
-import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { fail } from "./errors.js";
 const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const MAX_SKILL_BYTES = 256 * 1024;
+const BUILTIN_SKILL_NAMES = ["browser", "emulator"];
 export async function runSkillsCommand(args) {
     const [subcommand, name] = args;
     const json = args.includes("--json");
     if (subcommand === "list") {
         const skills = await listBuiltinSkills();
         if (json) {
-            console.log(JSON.stringify({ skills: skills.map(({ name: skillName }) => ({ name: skillName })) }, null, 2));
+            console.log(JSON.stringify({
+                topics: skills.map(({ name: topicName, description }) => ({
+                    name: topicName,
+                    description,
+                })),
+            }, null, 2));
         }
         else {
             for (const skill of skills)
-                console.log(skill.name);
+                console.log(`${skill.name}: ${skill.description}`);
         }
         return 0;
     }
@@ -23,15 +28,17 @@ export async function runSkillsCommand(args) {
         if (!name || name.startsWith("--")) {
             fail("skills get: missing Builtin Skill name");
         }
-        const skill = await readBuiltinSkill(name);
-        if (!skill)
-            fail(`Builtin Skill "${name}" was not found`);
+        const full = args.includes("--full");
+        const skill = await readBuiltinSkill(name, full);
+        if (!skill) {
+            const available = (await listBuiltinSkills()).map((entry) => entry.name).join(", ");
+            fail(`Unknown Skill guide "${name}". Available topics: ${available}`);
+        }
         if (json) {
             console.log(JSON.stringify({
                 name: skill.name,
-                directory: skill.directory,
-                skillFile: skill.skillFile,
-                content: skill.content,
+                full: skill.full,
+                markdown: skill.content,
             }, null, 2));
         }
         else {
@@ -44,21 +51,25 @@ export async function runSkillsCommand(args) {
     fail("skills: expected list or get <name>");
 }
 export async function listBuiltinSkills() {
-    const known = ["rynx-cli"];
-    const skills = await Promise.all(known.map((name) => readBuiltinSkill(name)));
-    return skills.filter((skill) => skill !== null);
+    const guides = await Promise.all(BUILTIN_SKILL_NAMES.map((name) => readBuiltinSkill(name)));
+    return guides.filter((guide) => guide !== null);
 }
-export async function readBuiltinSkill(name) {
+export async function readBuiltinSkill(name, full = false) {
     if (!SKILL_NAME_PATTERN.test(name))
         return null;
-    const directory = path.join(builtinSkillsDirectory(), name);
-    const skillFile = path.join(directory, "SKILL.md");
+    if (!BUILTIN_SKILL_NAMES.includes(name))
+        return null;
+    const guideFile = path.join(builtinSkillGuidesDirectory(), `${name}.md`);
     try {
-        const content = await readFile(skillFile, "utf8");
+        const content = await readFile(guideFile, "utf8");
         if (Buffer.byteLength(content, "utf8") > MAX_SKILL_BYTES) {
-            throw new Error(`Builtin Skill "${name}" exceeds ${MAX_SKILL_BYTES} bytes`);
+            throw new Error(`Builtin Skill guide "${name}" exceeds ${MAX_SKILL_BYTES} bytes`);
+        }
+        const metadata = parseGuideFrontmatter(content, guideFile);
+        if (metadata.name !== name) {
+            throw new Error(`Builtin Skill guide "${name}" declares name "${metadata.name}"`);
         }
-        return { name, directory, skillFile, content };
+        return { name, description: metadata.description, content, full };
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -66,15 +77,17 @@ export async function readBuiltinSkill(name) {
         throw error;
     }
 }
-export function builtinSkillsDirectory(moduleUrl = import.meta.url, env = process.env) {
-    const configured = env.RYNX_BUILTIN_SKILLS_DIR?.trim();
-    if (configured && path.isAbsolute(configured) && existsSync(configured)) {
-        return configured;
+/** Resolve only inside the independently published @rynx-ai/cli package.
+ * The source and compiled module depths are identical (`src|dist/commands`). */
+export function builtinSkillGuidesDirectory(moduleUrl = import.meta.url) {
+    return path.resolve(fileURLToPath(new URL("../../skill-guides/", moduleUrl)));
+}
+function parseGuideFrontmatter(markdown, sourcePath) {
+    const match = /^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/.exec(markdown);
+    const name = match && /^name:\s*(.+?)\s*$/m.exec(match[1])?.[1];
+    const description = match && /^description:\s*(.+?)\s*$/m.exec(match[1])?.[1];
+    if (!name || !description) {
+        throw new Error(`Builtin Skill guide must declare single-line name and description: ${sourcePath}`);
     }
-    const packaged = fileURLToPath(new URL("../../skills/", moduleUrl));
-    if (existsSync(packaged))
-        return packaged;
-    // Source-tree tests run before a package build has copied the canonical
-    // artifact. Published/App builds always take the packaged branch above.
-    return fileURLToPath(new URL("../../../../skills/", moduleUrl));
+    return { name, description: description.replace(/\s+/g, " ").trim() };
 }

package/dist/control-client.d.ts

@@ -3,7 +3,7 @@ import { type DaemonBrowserArtifactCleanResult, type DaemonBrowserArtifactInstal
 import { type RemoteRuntimeRpcMethod, type RemoteRuntimeRpcParams, type RemoteRuntimeRpcResultFor } from "@rynx-ai/protocol/remote-runtime-rpc";
 import { type PairingOffer } from "@rynx-ai/protocol/direct-runtime";
 import { type RuntimeBrowserBootstrapCredential, type RuntimeBrowserEndpointDescriptor } from "@rynx-ai/protocol/runtime-browser-bootstrap";
-import { type PluginInstallCommitInput, type PluginInstallCommitResult, type PluginInstallPreparation, type PluginInstallPrepareInput, type PluginManagementItem, type PluginManagementState } from "@rynx-ai/protocol/plugin-management";
+import { type PluginInstallCommitInput, type PluginInstallCommitResult, type PluginInstallPreparation, type PluginInstallPrepareInput, type PluginManagementItem, type PluginManagementState, type PluginMarketplaceAddInput, type PluginMarketplaceItem } from "@rynx-ai/protocol/plugin-management";
 export { connectResidentDesktopBrowserHost, type ResidentDesktopBrowserHostConnection, type ResidentDesktopBrowserHostCommandRequest, type ResidentDesktopBrowserHostConnectOptions, type ResidentDesktopBrowserHostFailure, } from "./desktop-browser-host-client.js";
 export interface ResidentDaemon {
     origin: string;
@@ -142,6 +142,10 @@ export declare function getResidentRuntimeLocalBrowserAutomationAccess(options?:
 export declare function invokeResidentPluginCommand(pluginId: string, args: readonly string[], options?: InvokeResidentPluginCommandOptions): Promise<ResidentPluginCommandResult>;
 /** Read the daemon-owned plugin registry without exposing package paths/specs. */
 export declare function listResidentPlugins(): Promise<ResidentPluginManagementItem[]>;
+export declare function listResidentPluginMarketplaces(): Promise<PluginMarketplaceItem[]>;
+export declare function addResidentPluginMarketplace(input: PluginMarketplaceAddInput): Promise<PluginMarketplaceItem>;
+export declare function refreshResidentPluginMarketplace(id: string): Promise<PluginMarketplaceItem>;
+export declare function removeResidentPluginMarketplace(id: string): Promise<boolean>;
 /** Enable or disable one installed plugin through authenticated management RPC. */
 export declare function setResidentPluginEnabled(pluginId: string, enabled: boolean): Promise<ResidentPluginManagementItem>;
 /** Remove one plugin registry entry through authenticated management RPC. */
@@ -149,13 +153,11 @@ export declare function uninstallResidentPlugin(pluginId: string): Promise<{
     uninstalled: true;
     pluginId: string;
 }>;
-/** Reload one plugin runtime after a durable registry mutation. */
-export declare function reloadResidentPluginRuntime(pluginId: string): Promise<Record<string, unknown>>;
 /** Materialize and hold one exact plugin artifact in daemon-owned staging. */
 export declare function prepareResidentPluginInstallation(input: PluginInstallPrepareInput, options?: {
     signal?: AbortSignal;
 }): Promise<PluginInstallPreparation>;
-/** Consume one preparation token and promote only its already-approved artifact. */
+/** Consume one preparation token and promote only its inspected artifact. */
 export declare function commitResidentPluginInstallation(token: string, input: PluginInstallCommitInput, options?: {
     signal?: AbortSignal;
 }): Promise<PluginInstallCommitResult>;

package/dist/control-client.js

@@ -6,7 +6,7 @@ import { parseRemoteRuntimeRpcRequest, parseRemoteRuntimeRpcResponseForMethod, R
 import { parsePairingOffer, } from "@rynx-ai/protocol/direct-runtime";
 import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_ENV, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_CONTEXT_FILE_ENV, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_SESSION_ID_ENV, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, parseRuntimeBrowserEndpointDescriptor, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
 import { parseRuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-browser";
-import { PLUGIN_INSTALL_PREPARATIONS_PATH, parsePluginInstallCommitInput, parsePluginInstallCommitResult, parsePluginInstallPreparation, parsePluginInstallPrepareInput, parsePluginManagementItem, pluginInstallCommitPath, pluginInstallPreparationPath, } from "@rynx-ai/protocol/plugin-management";
+import { PLUGIN_INSTALL_PREPARATIONS_PATH, PLUGIN_MARKETPLACES_PATH, parsePluginInstallCommitInput, parsePluginInstallCommitResult, parsePluginInstallPreparation, parsePluginInstallPrepareInput, parsePluginManagementItem, parsePluginMarketplaceAddInput, parsePluginMarketplaceItem, pluginInstallCommitPath, pluginInstallPreparationPath, } from "@rynx-ai/protocol/plugin-management";
 import { ensureDaemonControlEndpoint } from "./control-endpoint.js";
 export { connectResidentDesktopBrowserHost, } from "./desktop-browser-host-client.js";
 const IDENTITY_TIMEOUT_MS = 5_000;
@@ -42,7 +42,7 @@ const MAINTENANCE_RESPONSE_MAX_BYTES = 64 * 1024;
 const CHROME_INSPECTION_TIMEOUT_MS = 30_000;
 const CHROME_INSPECTION_RESPONSE_MAX_BYTES = 256 * 1024;
 const INSTALLATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const PLUGIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+const PLUGIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,62}@[a-z0-9][a-z0-9-]{0,62}(?:\/[a-z0-9][a-z0-9._-]{0,99})?$/;
 /** Stable error returned by the resident daemon's typed Runtime gateway. */
 export class ResidentRuntimeCallError extends Error {
     code;
@@ -671,6 +671,29 @@ export async function listResidentPlugins() {
     }
     return parsed.plugins.map(parsePluginManagementItem);
 }
+export async function listResidentPluginMarketplaces() {
+    const parsed = await pluginManagementRequest(PLUGIN_MARKETPLACES_PATH, { method: "GET" });
+    if (!Array.isArray(parsed.marketplaces)) {
+        throw new Error("daemon returned an invalid plugin marketplace list");
+    }
+    return parsed.marketplaces.map(parsePluginMarketplaceItem);
+}
+export async function addResidentPluginMarketplace(input) {
+    const validated = parsePluginMarketplaceAddInput(input);
+    return parsePluginMarketplaceItem(await pluginInstallRequest(PLUGIN_MARKETPLACES_PATH, { method: "POST", body: JSON.stringify(validated) }));
+}
+export async function refreshResidentPluginMarketplace(id) {
+    validateMarketplaceId(id);
+    return parsePluginMarketplaceItem(await pluginManagementRequest(`${PLUGIN_MARKETPLACES_PATH}/${encodeURIComponent(id)}/refresh`, { method: "POST" }));
+}
+export async function removeResidentPluginMarketplace(id) {
+    validateMarketplaceId(id);
+    const parsed = await pluginManagementRequest(`${PLUGIN_MARKETPLACES_PATH}/${encodeURIComponent(id)}`, { method: "DELETE" });
+    if (parsed.removed !== true) {
+        throw new Error("daemon returned an invalid plugin marketplace removal response");
+    }
+    return true;
+}
 /** Enable or disable one installed plugin through authenticated management RPC. */
 export async function setResidentPluginEnabled(pluginId, enabled) {
     validatePluginId(pluginId);
@@ -686,11 +709,6 @@ export async function uninstallResidentPlugin(pluginId) {
     }
     return { uninstalled: true, pluginId };
 }
-/** Reload one plugin runtime after a durable registry mutation. */
-export async function reloadResidentPluginRuntime(pluginId) {
-    validatePluginId(pluginId);
-    return pluginManagementRequest(`/api/internal/plugin-runtimes/${encodeURIComponent(pluginId)}/reload`, { method: "POST" });
-}
 /** Materialize and hold one exact plugin artifact in daemon-owned staging. */
 export async function prepareResidentPluginInstallation(input, options = {}) {
     const validated = parsePluginInstallPrepareInput(input);
@@ -701,7 +719,7 @@ export async function prepareResidentPluginInstallation(input, options = {}) {
     });
     return parsePluginInstallPreparation(response);
 }
-/** Consume one preparation token and promote only its already-approved artifact. */
+/** Consume one preparation token and promote only its inspected artifact. */
 export async function commitResidentPluginInstallation(token, input, options = {}) {
     const validated = parsePluginInstallCommitInput(input);
     const response = await pluginInstallRequest(pluginInstallCommitPath(token), {
@@ -762,6 +780,11 @@ function validatePluginId(pluginId) {
     if (!PLUGIN_ID_PATTERN.test(pluginId))
         throw new Error("invalid plugin id");
 }
+function validateMarketplaceId(id) {
+    if (!/^[a-z0-9][a-z0-9-]{0,62}(?:\/[a-z0-9][a-z0-9._-]{0,99})?$/.test(id)) {
+        throw new Error("invalid plugin marketplace id");
+    }
+}
 async function localManagementJsonRequest(pathname, input) {
     const endpoint = await ensureDaemonControlEndpoint();
     assertLoopbackOrigin(endpoint.origin);

package/dist/run-cli.js

@@ -4,8 +4,10 @@ import { runBrowserCommand } from "./commands/browser.js";
 import { runCleanupCommand } from "./commands/cleanup.js";
 import { runEmulatorCommand } from "./commands/emulator.js";
 import { fail } from "./commands/errors.js";
-import { runPluginCommand, runPluginManageCommand, } from "./commands/plugin.js";
+import { runMarketCommand } from "./commands/market.js";
+import { runPluginCommand, } from "./commands/plugin.js";
 import { runRuntimeCommand } from "./commands/runtime.js";
+import { runSessionCommand } from "./commands/session.js";
 import { runSkillsCommand } from "./commands/skills.js";
 import { runLegacyDaemonCli } from "./legacy-adapter.js";
 import { USAGE } from "./usage.js";
@@ -34,16 +36,17 @@ export async function runCli(argv) {
             console.log(installedVersion());
             return 0;
         case "plugin":
-            if (argv[1] === "manage") {
-                return runPluginManageCommand(argv.slice(2));
-            }
             return runPluginCommand(argv.slice(1));
+        case "market":
+            return runMarketCommand(argv.slice(1));
         case "agent":
             return runAgentCommand(argv.slice(1));
         case "emulator":
             return runEmulatorCommand(argv.slice(1));
         case "runtime":
             return runRuntimeCommand(argv.slice(1));
+        case "session":
+            return runSessionCommand(argv.slice(1));
         case "skills":
             return runSkillsCommand(argv.slice(1));
         case "browser":

package/dist/usage.d.ts

@@ -1 +1 @@
-export declare const USAGE = "Usage: rynx <command>\n\nGeneral:\n  version | --version  print the installed Rynx version\n\nSetup:\n  setup              interactive configuration wizard\n  doctor             read-only health check\n\nLifecycle:\n  start | restart | stop | status | logs\n  update [version] [--check] [--json]\n\nPlugins:\n  plugin manage list\n  plugin manage install <source> [--force] [--grant-all] [--expect-digest <sha256-...>] [...]\n  plugin manage update <id> [--grant-all] [--expect-digest <sha256-...>] [...]\n  plugin manage enable|disable|uninstall <id>\n  plugin <id> <command>       invoke a plugin command through daemon RPC\n\nAgents:\n  agent list\n  agent show <id>\n  agent add <id>\n  agent rm <id>\n\nBuiltin Skills:\n  skills list [--json]\n  skills get <name> [--json]\n\nMaintenance:\n  cleanup sessions [--dry-run]\n\nEmulator:\n  emulator <args...>\n\nRemote Runtime:\n  runtime share --address <host|ws-url> [--label <label>] [--json]\n  runtime add --pairing-code <rynx://...> [--name <name>]\n  runtime list [--json]\n  runtime test <local|daemon-id> [--json]\n  runtime forget <daemon-id>\n  runtime clients list [--json]\n  runtime clients revoke <grant-id>\n\nBrowser:\n  browser install|update|version|clean [...]\n  browser open [url] --session <id> [--runtime <local|daemon-id>] [--json]\n  browser status|pages|close --session <id> [--runtime <local|daemon-id>] [--json]\n  browser endpoint [--ensure] --session <local-id> [--json]\n  browser snapshot --session <local-id> [--json]\n  browser navigate <url> --session <local-id> [--json]\n  browser click (--ref <ref>|--selector <css>|--x <n> --y <n>) --session <local-id> [--json]\n  browser type (--ref <ref>|--selector <css>) --text <text> --session <local-id> [--json]\n  browser screenshot --output <absolute-path> --session <local-id> [--json]\n";
+export declare const USAGE = "Usage: rynx <command>\n\nGeneral:\n  version | --version  print the installed Rynx version\n\nSetup:\n  setup              interactive configuration wizard\n  doctor             read-only health check\n\nLifecycle:\n  start | restart | stop | status | logs\n  update [version] [--check] [--json]\n\nPlugins:\n  market list\n  market add <git-or-local-source> [--alias <id>]\n  market refresh [market-id]\n  market remove <market-id>\n  plugin list\n  plugin install <source|plugin@market> [--force] [--expect-digest <sha256-...>]\n  plugin update <plugin@market> [--expect-digest <sha256-...>]\n  plugin enable|disable|uninstall <plugin@market>\n  plugin <plugin@market> <command>  invoke a plugin-owned command\n\nAgents:\n  agent list\n  agent show <id>\n  agent add <id>\n  agent rm <id>\n\nBuiltin Skills:\n  skills list [--json]\n  skills get <browser|emulator> [--full] [--json]\n\nMaintenance:\n  cleanup sessions [--dry-run]\n\nEmulator:\n  emulator <args...>\n\nRemote Runtime:\n  runtime share --address <host|ws-url> [--label <label>] [--json]\n  runtime add --pairing-code <rynx://...> [--name <name>]\n  runtime list [--json]\n  runtime test <local|daemon-id> [--json]\n  runtime forget <daemon-id>\n  runtime clients list [--json]\n  runtime clients revoke <grant-id>\n\nSessions:\n  session fork <session-id> [--title <title>] [--json]\n\nBrowser:\n  browser install|update|version|clean [...]\n  browser open [url] [--session <id>] [--runtime <local|daemon-id>] [--json]\n  browser status|pages|close [--session <id>] [--runtime <local|daemon-id>] [--json]\n  browser endpoint [--ensure] [--session <local-id>] [--json]\n  browser snapshot [--session <local-id>] [--json]\n  browser navigate <url> [--session <local-id>] [--json]\n  browser click (--ref <ref>|--selector <css>|--x <n> --y <n>) [--session <local-id>] [--json]\n  browser type (--ref <ref>|--selector <css>) --text <text> [--session <local-id>] [--json]\n  browser screenshot --output <absolute-path> [--session <local-id>] [--json]\n";

package/dist/usage.js

@@ -12,11 +12,15 @@ Lifecycle:
   update [version] [--check] [--json]
 
 Plugins:
-  plugin manage list
-  plugin manage install <source> [--force] [--grant-all] [--expect-digest <sha256-...>] [...]
-  plugin manage update <id> [--grant-all] [--expect-digest <sha256-...>] [...]
-  plugin manage enable|disable|uninstall <id>
-  plugin <id> <command>       invoke a plugin command through daemon RPC
+  market list
+  market add <git-or-local-source> [--alias <id>]
+  market refresh [market-id]
+  market remove <market-id>
+  plugin list
+  plugin install <source|plugin@market> [--force] [--expect-digest <sha256-...>]
+  plugin update <plugin@market> [--expect-digest <sha256-...>]
+  plugin enable|disable|uninstall <plugin@market>
+  plugin <plugin@market> <command>  invoke a plugin-owned command
 
 Agents:
   agent list
@@ -26,7 +30,7 @@ Agents:
 
 Builtin Skills:
   skills list [--json]
-  skills get <name> [--json]
+  skills get <browser|emulator> [--full] [--json]
 
 Maintenance:
   cleanup sessions [--dry-run]
@@ -43,14 +47,17 @@ Remote Runtime:
   runtime clients list [--json]
   runtime clients revoke <grant-id>
 
+Sessions:
+  session fork <session-id> [--title <title>] [--json]
+
 Browser:
   browser install|update|version|clean [...]
-  browser open [url] --session <id> [--runtime <local|daemon-id>] [--json]
-  browser status|pages|close --session <id> [--runtime <local|daemon-id>] [--json]
-  browser endpoint [--ensure] --session <local-id> [--json]
-  browser snapshot --session <local-id> [--json]
-  browser navigate <url> --session <local-id> [--json]
-  browser click (--ref <ref>|--selector <css>|--x <n> --y <n>) --session <local-id> [--json]
-  browser type (--ref <ref>|--selector <css>) --text <text> --session <local-id> [--json]
-  browser screenshot --output <absolute-path> --session <local-id> [--json]
+  browser open [url] [--session <id>] [--runtime <local|daemon-id>] [--json]
+  browser status|pages|close [--session <id>] [--runtime <local|daemon-id>] [--json]
+  browser endpoint [--ensure] [--session <local-id>] [--json]
+  browser snapshot [--session <local-id>] [--json]
+  browser navigate <url> [--session <local-id>] [--json]
+  browser click (--ref <ref>|--selector <css>|--x <n> --y <n>) [--session <local-id>] [--json]
+  browser type (--ref <ref>|--selector <css>) --text <text> [--session <local-id>] [--json]
+  browser screenshot --output <absolute-path> [--session <local-id>] [--json]
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/cli",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "skill-guides"
   ],
   "bin": {
     "rynx": "./dist/cli.js"
@@ -38,10 +39,10 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.10",
-    "@rynx-ai/emulator": "0.1.10",
-    "@rynx-ai/protocol": "0.1.10",
-    "@rynx-ai/browser-cdp": "0.1.10"
+    "@rynx-ai/browser-cdp": "0.1.11-beta.2",
+    "@rynx-ai/core": "0.1.11-beta.2",
+    "@rynx-ai/emulator": "0.1.11-beta.2",
+    "@rynx-ai/protocol": "0.1.11-beta.2"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"

package/skill-guides/browser.md

@@ -0,0 +1,72 @@
+---
+name: browser
+description: Use the bundled Rynx CLI to inspect and automate the Browser owned by the active Rynx Session with snapshots, accessibility refs, navigation, clicks, typing, screenshots, page inspection, and safe failure handling.
+---
+
+# Rynx Browser
+
+Use the bundled `rynx` executable supplied by the active Rynx Session. Choose
+that executable once and reuse it. Do not locate another installation with
+`which`, `npx`, npm, filesystem searches, App-name guesses, or alternate paths.
+
+The active Session already owns the resident daemon, Browser host, and Session
+binding. Omit `--session`; the managed Session credential scopes every command
+to the current Session. Prefer `--json`.
+
+## Sandbox boundary
+
+If a `rynx browser ...` command cannot connect to its local endpoint, do not
+interpret that as a stopped daemon. Stop and ask the user to approve rerunning
+the exact same command outside the Agent sandbox.
+
+Do not change the command or try another executable, endpoint, port, transport,
+installation, App, browser, or service. Do not scan `/Applications`, use `find`
+or `mdfind`, run `open`, `open -a`, or `osascript`, inspect Preview/dev builds,
+or launch/relaunch a Rynx App or daemon.
+
+## Core loop
+
+Open or navigate the Session Browser when needed:
+
+```sh
+rynx browser open https://example.com --json
+rynx browser navigate https://example.com/next --json
+```
+
+Inspect before acting:
+
+```sh
+rynx browser snapshot --json
+```
+
+Use a returned accessibility `ref` for the next action:
+
+```sh
+rynx browser click --ref <ref> --json
+rynx browser type --ref <ref> --text "hello" --json
+```
+
+Take a fresh snapshot after navigation or substantial DOM replacement because
+old refs become stale. Use `--selector` only when no useful accessibility ref
+exists. Use coordinate clicks only as a final fallback after a screenshot.
+
+Inspect pages and save visual evidence with:
+
+```sh
+rynx browser status --json
+rynx browser pages --json
+rynx browser screenshot --output /absolute/path/page.png --json
+```
+
+Do not request or connect to the raw CDP endpoint unless diagnosing Rynx itself.
+Do not close a Browser generation the user still needs.
+
+## Failure handling
+
+- On endpoint access failure, follow **Sandbox boundary** and make no fallback
+  attempt.
+- On `stale reference`, take a new snapshot and retry once.
+- On `busy`, preserve the current Turn or Terminal for the user to resolve.
+- On an unavailable capability, report the missing App integration or macOS
+  permission; do not install an unpinned replacement.
+- Preserve structured error codes and relevant stderr when reporting failure.

package/skill-guides/emulator.md

@@ -0,0 +1,79 @@
+---
+name: emulator
+description: Use the bundled Rynx CLI to inspect and control the iOS Simulator, Android emulator, or adb-visible Android device bound to the active Rynx Session, including device discovery, attach, taps, typing, buttons, screenshots, rotation, launch, and gestures.
+---
+
+# Rynx Emulator
+
+Use the bundled `rynx` executable supplied by the active Rynx Session and run
+Emulator operations through `rynx emulator ...`. Choose that executable once
+and reuse it. Do not locate another CLI or call `serve-sim`, `simctl`, or `adb`
+directly.
+
+The active Session already owns the resident daemon and Session binding. Use the
+Session's bound device by default. Add `--runtime <local|daemon-id>` only when
+the user explicitly selected another paired Runtime. Prefer `--json`.
+
+## Sandbox boundary
+
+If a `rynx emulator ...` command cannot connect to its local endpoint, do not
+interpret that as a stopped daemon. Stop and ask the user to approve rerunning
+the exact same command outside the Agent sandbox.
+
+Do not change the command or try another executable, endpoint, port, transport,
+installation, App, or service. Do not scan `/Applications`, use `find` or
+`mdfind`, run `open`, `open -a`, or `osascript`, inspect Preview/dev builds, or
+launch/relaunch a Rynx App or daemon.
+
+## Inspect and select
+
+Inspect current state before acting:
+
+```sh
+rynx emulator devices --json
+rynx emulator active --json
+```
+
+Attach only when no suitable device is already bound or the user asks to switch:
+
+```sh
+rynx emulator attach <device-id-or-exact-name> --json
+```
+
+Never reuse a device id, serial, or name remembered from another Session. After
+switching or reconnecting, read `active --json` again.
+
+## Control loop
+
+```sh
+rynx emulator tap <x> <y> --json
+rynx emulator type "hello" --json
+rynx emulator type --mode keys "hello" --json
+rynx emulator button home --json
+rynx emulator button backspace --json
+rynx emulator button appswitch --json
+rynx emulator screenshot --json
+rynx emulator rotate portrait --json
+rynx emulator launch <bundle-id-or-package> --json
+rynx emulator gesture '<json-points>' --json
+```
+
+Coordinates are normalized `0..1` with top-left origin. Re-inspect with a
+screenshot after every meaningful UI-changing action.
+
+For `launch`, use an exact iOS `CFBundleIdentifier` or Android package name.
+Never pass a display name or guess an identifier. If only a visible app name is
+known, navigate visually and confirm with screenshots.
+
+Do not run `exec`, `kill`, or `shutdown` as routine cleanup. Raw host commands
+and device/process lifecycle changes require an explicit user request.
+
+## Failure handling
+
+- On endpoint access failure, follow **Sandbox boundary** and make no fallback
+  attempt.
+- On a missing/stale device, refresh `devices --json` and `active --json`.
+- On `busy`, preserve the current Turn or Terminal for the user to resolve.
+- On an unavailable capability, report the missing integration or macOS
+  permission; do not install an unpinned replacement.
+- Preserve structured error codes and relevant stderr when reporting failure.

package/skills/rynx-cli/SKILL.md

@@ -1,99 +1,31 @@
 ---
 name: rynx-cli
-description: Operate Rynx-managed local and remote runtimes through the bundled `rynx` CLI, including Browser inspection and automation, Emulator control, runtime pairing, and plugin commands. Use when a task needs to inspect or act on a Rynx Session Browser or Emulator, manage a Rynx runtime target, or invoke a Rynx plugin. Prefer this bundled CLI over direct CDP calls, guessed ports, globally installed browser drivers, or ad-hoc device tools.
+description: Use the bundled `rynx` CLI when a task needs to inspect or automate the Browser or Emulator owned by the active Rynx Session. Load the version-matched Browser or Emulator guide from the CLI before operating it. Prefer this over direct CDP, browser drivers, `serve-sim`, `simctl`, adb, guessed ports, or guessed App installations.
 ---
 
 # Rynx CLI
 
-Use the bundled `rynx` command. Rynx supplies the correct executable and current
-Session context; do not locate another installation with `which`, `npx`, or npm.
+This file is a discovery stub, not the usage guide. Rynx injects it into an
+active Session only so the Agent can discover the capability without carrying a
+stale copy of the CLI command surface.
 
-## Choose the target
+Use the bundled `rynx` executable supplied by the Session. Do not locate or try
+another installation with `which`, `npx`, npm, filesystem searches, App-name
+guesses, or alternate executable paths.
 
-- Inside a Rynx Session, omit `--session`; the injected Session credential
-  restricts commands to that Session.
-- Outside a managed Session, pass `--session <id>`.
-- Add `--runtime <local|daemon-id>` only when the user explicitly selected a
-  different paired Runtime.
-- Prefer `--json` for inspection and automation output.
+Before running an operational command, load only the matching version-matched
+guide from that exact CLI:
 
-If the CLI reports that the daemon is unavailable, ask the user to open Rynx or
-enable its resident daemon. Never start an unrelated service or guess a port.
-
-## Browser workflow
-
-Open the Session Browser when needed:
-
-```sh
-rynx browser open https://example.com --json
-```
-
-Inspect before acting:
-
-```sh
-rynx browser snapshot --json
-```
-
-Use a returned `ref` for the next action. Take a fresh snapshot after navigation
-or substantial DOM replacement because old references become stale.
-
-```sh
-rynx browser click --ref <ref> --json
-rynx browser type --ref <ref> --text "hello" --json
-rynx browser navigate https://example.com/next --json
-rynx browser screenshot --output /absolute/path/page.png --json
+```text
+rynx skills get browser
+rynx skills get emulator
 ```
 
-Use `--selector` only when no useful accessibility reference exists. Use
-coordinate clicks only as a final fallback after a screenshot.
-
-Useful inspection commands:
-
-```sh
-rynx browser status --json
-rynx browser pages --json
-```
-
-Do not request or connect to the raw CDP endpoint unless diagnosing Rynx itself.
-Do not close a Browser generation that the user still needs.
-
-## Emulator workflow
-
-Inspect available commands and devices before acting:
-
-```sh
-rynx emulator --help
-rynx emulator devices
-rynx emulator active
-```
-
-Use the Session's bound device by default. Select another device or Runtime only
-when the user asks. Re-inspect the screen after every navigation or state-changing
-input, and never call `kill` or `shutdown` as cleanup unless requested.
-
-## Runtime and plugin operations
-
-List and test Runtime targets before selecting a remote target:
-
-```sh
-rynx runtime list --json
-rynx runtime test <local|daemon-id> --json
-```
-
-Invoke plugin-declared commands through:
-
-```sh
-rynx plugin <plugin-id> <command> --json
-```
-
-Treat pairing, client revocation, plugin installation, Browser engine updates,
-and daemon lifecycle changes as administrative operations. Perform them only
-when the user explicitly requests them.
-
-## Failure handling
+Use `browser` for Browser inspection/automation and `emulator` for mobile device
+inspection/control. Do not load an unrelated guide. These commands read guides
+shipped in the exact CLI npm package and do not contact the daemon or network.
 
-- On `stale reference`, take a new Browser snapshot and retry once.
-- On `busy`, preserve the current Turn or Terminal and let the user resolve it.
-- On an unavailable capability, report the missing App integration or macOS
-  permission; do not install an unpinned replacement.
-- Preserve structured error codes and relevant stderr when reporting failure.
+If `rynx skills get <topic>` itself cannot execute, report its exact error and
+stop. Do not scan `/Applications`, use `find` or `mdfind`, run `open`, `open -a`,
+or `osascript`, inspect Preview/dev builds, start a daemon, guess a port, or try
+a different Rynx App or CLI.