rl-workspaces 0.6.0 → 0.7.0

package/dist/picker.js

@@ -15,22 +15,37 @@ const stateColors = {
     none: 90,
     unknown: 90,
 };
-export function candidates(repo, base) {
-    return worktrees(repo)
+export function candidates(repo, base, store) {
+    const adopted = new Map(store
+        ?.records()
+        .filter(([, data]) => data.status === "active")
+        .map(([, data]) => [data.worktree, data.branch]));
+    const records = worktrees(repo)
         .slice(1)
         .flatMap((record) => {
         const root = canonical(record.worktree);
-        if (root === repo || !inside(root, base))
+        const managed = inside(root, base);
+        const branch = (record.branch ?? "").replace(/^refs\/heads\//, "");
+        if (root === repo || (!managed && adopted.get(root) !== branch))
             return [];
         return [
             {
-                name: path.relative(base, root),
+                name: managed ? path.relative(base, root) : path.basename(root),
                 path: root,
-                branch: (record.branch ?? "").replace(/^refs\/heads\//, ""),
+                branch,
                 locked: "locked" in record,
             },
         ];
     });
+    // Preserve existing managed names. Outside checkouts use their directory
+    // name unless it collides, in which case their absolute path is unambiguous.
+    const used = new Set(records.filter((item) => inside(item.path, base)).map((item) => item.name));
+    for (const item of records.filter((item) => !inside(item.path, base))) {
+        if (used.has(item.name))
+            item.name = item.path;
+        used.add(item.name);
+    }
+    return records;
 }
 export function prState(data) {
     if (!data?.pr)
@@ -120,7 +135,9 @@ export function pickerRows(store, items, defaultBase, prs = new Map()) {
 }
 export async function select(store, items, defaultBase, multiple) {
     if (!items.length) {
-        console.error("No managed worktrees to " + (multiple ? "delete." : "open."));
+        console.error(multiple
+            ? "No managed worktrees to delete."
+            : "No RL workspaces yet. Create one with rl switch <name> --create.");
         return [];
     }
     const prs = await discoverPrs(store, items.map((item) => item.branch));
@@ -175,7 +192,7 @@ export async function main(argv) {
     ]);
     arity(positionals, 0);
     const store = new Store(required(values, "repo"), required(values, "state-dir"));
-    const selected = await select(store, candidates(store.repo, canonical(required(values, "base-dir"))), required(values, "default-base"), false);
+    const selected = await select(store, candidates(store.repo, canonical(required(values, "base-dir")), store), required(values, "default-base"), false);
     if (selected.length)
         process.stdout.write(selected[0].path + "\n");
     return 0;

package/dist/pr-workflow.js

@@ -2,12 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { args, arity, canonical, execute, git, inside, locked, } from "./common.js";
-import { commandContext, contextOptions, resolveWorkspace, } from "./command-context.js";
+import { commandContext, contextOptions } from "./command-context.js";
 import { GIT_WORKFLOW_DIRECTORY, GIT_WORKFLOW_LOCK } from "./git-safety.js";
 import { isJsonObject, parseJsonObject } from "./json.js";
 const GH_TIMEOUT_MS = 20_000;
 const PR_FIELDS = "number,url,headRefName,headRefOid,baseRefName,isCrossRepository,headRepository,headRepositoryOwner";
-const CHECK_FIELDS = "name,state,bucket,link,workflow";
 const FETCH_PREFIX = "refs/rl/pr-fetch/";
 /** Bound requests and ignore a caller's unrelated GH_REPO override. */
 export async function github(repo, argv) {
@@ -53,33 +52,13 @@ export async function repositoryIdentity(repo) {
     return { name: raw.nameWithOwner, url: raw.url };
 }
 export async function main(argv) {
-    const { values, positionals } = args(argv, [...contextOptions, "name"], ["json"]);
-    const context = commandContext(values);
+    const { values, positionals } = args(argv, [...contextOptions, "name"], []);
     const [command, action, ...rest] = positionals;
-    if (command !== "pr" || !["checks", "checkout"].includes(action))
-        throw new Error("Usage: rl pr checks|checkout");
-    const identity = await repositoryIdentity(context.repo);
-    if (action === "checks") {
-        arity(rest, 0);
-        if (values.name)
-            throw new Error("checks does not accept --name");
-        const workspace = resolveWorkspace(context);
-        const result = await github(workspace.path, [
-            "pr",
-            "checks",
-            workspace.branch,
-            "--repo",
-            identity.url,
-            ...(values.json ? ["--json", CHECK_FIELDS] : []),
-        ]);
-        process.stdout.write(result.stdout);
-        if (result.stderr)
-            process.stderr.write(result.stderr);
-        return result.code;
-    }
+    if (command !== "pr" || action !== "checkout")
+        throw new Error("Usage: rl pr checkout <number> [--name <branch>]");
     arity(rest, 1);
-    if (values.json)
-        throw new Error("checkout does not accept --json");
+    const context = commandContext(values);
+    const identity = await repositoryIdentity(context.repo);
     const [number] = rest;
     if (!/^[1-9]\d*$/.test(number))
         throw new Error("Expected a positive PR number");
@@ -149,7 +128,7 @@ export async function main(argv) {
             }
             catch (error) {
                 // Preserve the valid checkout on adoption failure so hooks/files can be inspected.
-                throw new Error(`Created ${destination}, but RL adoption failed: ${error instanceof Error ? error.message : "unknown error"}. Run rl adopt inside it`);
+                throw new Error(`Created ${destination}, but RL adoption failed: ${error instanceof Error ? error.message : "unknown error"}. Run rl setup adopt inside it`);
             }
             console.log(destination);
             return 0;

package/dist/repos.js

@@ -183,7 +183,11 @@ class Registry {
                 if (rest.length === 3 && values.alias !== undefined)
                     throw new Error("Choose either --alias <name> or the legacy <alias> <path> form");
                 const target = rest.length === 3 ? rest[2] : (rest[1] ?? ".");
-                const root = canonical(worktrees(expandHome(target))[0].worktree);
+                const directoryPath = path.resolve(expandHome(target));
+                if (!fs.existsSync(directoryPath) ||
+                    !fs.statSync(directoryPath).isDirectory())
+                    throw new Error(`Repository directory does not exist: ${directoryPath}. Use 'rl repo add .' for the current repository, with --alias <name> to name it.`);
+                const root = canonical(worktrees(directoryPath)[0].worktree);
                 name = String(values.alias ?? (rest.length === 3 ? name : repositoryName(root)));
                 if (!validName(name))
                     throw new Error("Repository names must contain letters, numbers, dots, underscores, or hyphens; supply --alias <name>");

package/dist/session-workflows.js

@@ -223,7 +223,7 @@ export function automationContext(root) {
         .digest("hex");
     return [
         `RL native agent configuration detected (${fingerprint}; source: ${hasAutomation(root) ? "workspace configuration" : "built-in defaults"}; default workflow: ${defaultWorkflow(config)}). You are the coordinator of this session's own native subagents.`,
-        "Discover profiles, workflow dependencies, trigger rules and policies with rl_workflow_context (MCP), or 'rl workflow context --json'. At planning milestones report the configured event with rl_workflow_event. Tool and before-finish hooks also queue matching requests. Read pending requests with rl_workflow_pending.",
+        "Use RL from this existing session; no special agent launcher or user-pasted workflow prompt is required. Run 'rl workflow context --json' to discover the active profiles, workflows, policies and the complete protocol.tools CLI commands and input schemas. Use the CLI through your normal shell tools; an MCP connection is optional. If MCP tools are connected, the same operation names and schemas apply. Follow the active configuration automatically for applicable tasks. At planning milestones report the configured event with rl_workflow_event. Tool and before-finish hooks also queue matching requests. Read pending requests with rl_workflow_pending.",
         "For coding tasks, report task_planned before implementation. A collaborative workflow starts all writer, reviewer and DRY native peers in parallel: claim all three roles, spawn them using your native tools, bind their handles with rl_workflow_bind, then relay messages or let peers use their own inbox. The writer submits checkpoints, the reviewer returns policy-based ratings, and DRY answers both peers. Keep all three peers available; do not replace them with sequential one-shot passes. Use collaboration tools for handoffs before final stage reports. Semantic new-function and duplication obligations require explicit declarations and consultation responses; RL cannot read private reasoning.",
         "For each request: rl_workflow_start creates a run tied to YOUR parent session; rl_workflow_claim atomically returns a ready step and its instructions. Spawn that step with YOUR native subagent tool, then submit its evidence with rl_workflow_report. Run command steps yourself and report actual output. RL never starts Codex, Claude, or check processes for a workflow. Do not substitute a separate CLI or API agent. Respect current permissions, workspace boundaries, explicit user instructions and native delegation availability. If delegation is unavailable, dismiss the request with the concrete reason and tell the user; do not claim it ran.",
         "Supply agent (codex or claude) and this parent conversation's full sessionId to workflow tools. UUIDs and observed Codex thr_ IDs are supported for workflow coordination; only verified UUIDs enter resumable history. CLI equivalents: 'rl workflow pending', 'rl workflow run --request <requestId>', 'rl workflow claim <run> --step <step>', 'rl workflow report <run> --file <report.json>', with --agent and --session. Profiles describe roles; their provider field is a legacy preference, never permission to start another provider. Unsupported native model/reasoning preferences must be reported, not silently substituted. Policies own scoring; return evidence without assigning yourself a score.",
@@ -320,6 +320,75 @@ export const WORKFLOW_TOOLS = [
     },
     ...COLLABORATION_TOOLS,
 ];
+export function workflowToolSchema(tool) {
+    return {
+        type: "object",
+        properties: {
+            agent: { type: "string", enum: ["codex", "claude"] },
+            sessionId: {
+                type: "string",
+                description: "Current parent conversation ID. Claude requires a UUID; Codex also accepts observed thr_ IDs and may inherit it.",
+            },
+            ...tool.properties,
+        },
+        required: tool.required,
+        additionalProperties: false,
+    };
+}
+function workflowProtocol() {
+    const identity = { agent: "--agent", sessionId: "--session" };
+    return {
+        version: 1,
+        coordinator: "current-session",
+        requiresMcp: false,
+        requiresRlLauncher: false,
+        requiresNativeSubagents: true,
+        discovery: "rl workflow context --json",
+        instruction: "Use your current session's native subagent and messaging tools. RL supplies roles and coordination state. CLI operations below use the same inputSchema as MCP; tools with stdin: json accept the entire input object via --file -. These are coordination commands, never instructions to start a second provider process.",
+        tools: WORKFLOW_TOOLS.map((tool) => {
+            const action = tool.name.slice("rl_workflow_".length);
+            const file = !["context", "pending", "start", "claim", "inbox"].includes(action);
+            const flags = action === "start"
+                ? {
+                    ...identity,
+                    base: "--base",
+                    prompt: "--prompt",
+                    requestId: "--request",
+                }
+                : {
+                    ...identity,
+                    ...(action === "claim" || action === "inbox"
+                        ? { step: "--step" }
+                        : {}),
+                    ...(action === "inbox" ? { claim: "--claim" } : {}),
+                };
+            return {
+                name: tool.name,
+                description: tool.description,
+                inputSchema: workflowToolSchema(tool),
+                cli: {
+                    command: [
+                        "rl",
+                        "workflow",
+                        action === "start" ? "run" : action,
+                        ...(file ? ["--file", "-"] : []),
+                        "--json",
+                    ],
+                    stdin: file ? "json" : "none",
+                    positionals: file
+                        ? []
+                        : action === "start"
+                            ? ["workflow"]
+                            : action === "claim" || action === "inbox"
+                                ? ["run"]
+                                : [],
+                    flags: file ? {} : flags,
+                    output: "json",
+                },
+            };
+        }),
+    };
+}
 export async function callWorkflowTool(store, name, input) {
     const definition = WORKFLOW_TOOLS.find((tool) => tool.name === name);
     if (!definition)
@@ -337,6 +406,7 @@ export async function callWorkflowTool(store, name, input) {
             source: hasAutomation(data.worktree) ? "workspace" : "built-in",
             ...readAutomation(data.worktree),
             instructions: automationContext(data.worktree),
+            protocol: workflowProtocol(),
         };
     }
     const parent = owner(input);

package/dist/session.js

@@ -7,6 +7,6 @@ export function currentSessionId(agent, explicit) {
     // Resume the current conversation, including a fork, rather than its tree root.
     const id = process.env.CODEX_THREAD_ID ?? process.env.CODEX_SESSION_ID;
     if (!id)
-        throw new Error("No current Codex session ID. Run 'rl session save codex' inside Codex, or supply the full UUID: rl session save codex <UUID>");
+        throw new Error("No current Codex session ID. Run 'rl agent save codex' inside Codex, or supply the full UUID: rl agent save codex <UUID>");
     return sessionId(id);
 }

package/dist/state.js

@@ -145,7 +145,7 @@ export async function main(argv) {
         arity(rest, 0, rest[0] === "open" ? 1 : 0);
         return openPr(store, !!values.json);
     }
-    if (command === "status" || command === "instances")
+    if (command === "status")
         arity(rest, 0);
     if (command === "session" && rest[0] === "list") {
         arity(rest, 1, 2);
@@ -154,10 +154,8 @@ export async function main(argv) {
     }
     if (command === "status" && values.fetch)
         git(store.repo, "fetch", "--all", "--prune");
-    if (command === "status" ||
-        command === "instances" ||
-        (command === "session" && rest[0] === "list"))
-        await syncCodexSessions(store, command === "instances" ? undefined : process.cwd());
+    if (command === "status" || (command === "session" && rest[0] === "list"))
+        await syncCodexSessions(store, process.cwd());
     let replacement = "";
     if (["context", "progress"].includes(command) &&
         ["set", "append"].includes(rest[0])) {
@@ -165,14 +163,6 @@ export async function main(argv) {
         replacement = fs.readFileSync(rest[1] === "-" ? 0 : rest[1], "utf8");
     }
     return store.locked(() => {
-        if (command === "instances") {
-            arity(rest, 0);
-            json(store.records().map(([, data]) => ({
-                ...data,
-                gitStatus: branchStatus(store.repo, data),
-            })));
-            return 0;
-        }
         if (command === "archive") {
             arity(rest, 0);
             const root = canonical(required(values, "worktree"));
@@ -219,7 +209,7 @@ export async function main(argv) {
                 json(rest[1] ? data.sessions[agent(rest[1])] : data.sessions);
             }
             else
-                throw new Error("Usage: rl session list [agent] | save [agent] [UUID] | add <agent> <UUID>");
+                throw new Error("Usage: rl agent sessions [agent] | save [agent] [UUID]");
         }
         else if (command === "context" || command === "progress") {
             const target = path.join(path.dirname(file), command + ".md"), action = rest[0];

package/dist/storage.js

@@ -239,7 +239,7 @@ function remove(workspace, targets, recheck) {
 function suggestions(data, usage, estimatedBytes, days) {
     const result = [];
     if (estimatedBytes)
-        result.push(`Run rl clean --dry-run to preview ${size(estimatedBytes)} of configured generated files.`);
+        result.push(`Run rl storage clean --dry-run to preview ${size(estimatedBytes)} of configured generated files.`);
     else if (usage.dependenciesBytes || usage.buildsBytes)
         result.push("Add generated directory paths to the clean list in this workspace's .rl/workflows.json.");
     const accessed = lastAccessed(data);
@@ -256,7 +256,7 @@ export async function main(argv) {
     if (!["storage", "clean"].includes(command) ||
         (command === "storage" && values["dry-run"]) ||
         (command === "clean" && values["older-than"] !== undefined))
-        throw new Error("Usage: rl storage [--json] [--older-than 14d] | rl clean [--dry-run] [--json] (current workspace only)");
+        throw new Error("Usage: rl storage [--json] [--older-than 14d] | rl storage clean [--dry-run] [--json] (current workspace only)");
     const context = commandContext(values);
     // Resolve from the caller's cwd before any scan, lock creation, or mutation.
     const [file, data] = context.store.current();

package/dist/store.js

@@ -183,7 +183,7 @@ export class Store {
                     throw new Error(`Instance owns branch ${data.branch}; current branch is ${branch}`);
                 return [file, data];
             }
-        throw new Error("No RL instance for this worktree. Run 'rl adopt' first");
+        throw new Error("No RL instance for this worktree. Run 'rl setup adopt' first");
     }
     save(file, data) {
         data.updatedAt = now();
@@ -359,7 +359,7 @@ function installHooks(store, file, data) {
 export function contextText(file, data) {
     const sections = [
         `RL feature workspace: ${data.id}\nBranch: ${data.branch}`,
-        "The following RL-owned documents are shared living feature documentation, not just conversation memory. Read them before starting work, and read the full files when excerpts are truncated. At meaningful milestones and before finishing your task, document what changed, what remains, implementation details (file/symbol references, flows, APIs, data structures), decisions and rationale, checks actually run, and blockers. Keep completed and planned work distinct; do not mark unverified work as tested or done. Respect your assigned scope and permissions; read-only agents should return proposed documentation updates to their parent. Use 'rl context append <file>' for durable domain or design notes and 'rl progress append <file>' for milestone/handoff updates ('-' reads stdin). Append is locked so concurrent agents do not overwrite one another. Use 'rl context set <file>' or 'rl progress set <file>' only for a deliberate replacement after reading the latest document and coordinating with other writers. Re-read the documents before planning subsequent work.",
+        "The following RL-owned documents are shared living feature documentation, not just conversation memory. Read them before starting work, and read the full files when excerpts are truncated. At meaningful milestones and before finishing your task, document what changed, what remains, implementation details (file/symbol references, flows, APIs, data structures), decisions and rationale, checks actually run, and blockers. Keep completed and planned work distinct; do not mark unverified work as tested or done. Respect your assigned scope and permissions; read-only agents should return proposed documentation updates to their parent. Use 'rl notes append context <file>' for durable domain or design notes and 'rl notes append progress <file>' for milestone/handoff updates ('-' reads stdin). Append is locked so concurrent agents do not overwrite one another. Use 'rl notes set context <file>' or 'rl notes set progress <file>' only for a deliberate replacement after reading the latest document and coordinating with other writers. Re-read the documents before planning subsequent work.",
     ];
     sections.push("When the user asks to pause or save this task for later, save a task handoff with rl_task_pause through MCP, or 'rl pause --summary <text> --changes <text> --validation <text> --next <text> [--blockers <text>]'. Include the current session UUID (Codex shell commands can infer it), concrete changes, checks actually run and their results, remaining work, and blockers. Use 'Not run' for unperformed checks. A pause saves task state; it does not terminate the agent. The user can return with 'rl continue'.");
     const automation = automationContext(data.worktree);

package/dist/summary.js

@@ -86,7 +86,7 @@ function render(store, data, context, progress, defaultBase, requested) {
         parts.push("### Committed file changes", changes ? fence(changes) : "No net committed file changes.");
     }
     else
-        parts.push(`The configured comparison base ${inline(comparison)} could not be resolved. Committed work was omitted; run \`rl summary --base <branch-or-commit>\` to include it.`);
+        parts.push(`The configured comparison base ${inline(comparison)} could not be resolved. Committed work was omitted; run \`rl notes summary --base <branch-or-commit>\` to include it.`);
     parts.push("## Uncommitted work", `Git status entries: ${status.staged} staged, ${status.unstaged} unstaged, ${status.untracked} untracked, ${status.conflicts} conflicts. An untracked directory counts as one status entry.`);
     for (const [title, flags] of [
         ["Staged changes", ["--cached"]],

package/dist/workflow.js

@@ -16,8 +16,6 @@ const COMMAND_OPTIONS = {
     exec: ["workspace"],
     setup: ["workspace", "dry-run"],
     switch: ["create", "base", "no-fetch", "setup", "agent", "output-path"],
-    new: ["base", "no-fetch", "setup", "output-path"],
-    open: ["branch", "base", "no-fetch", "setup", "output-path"],
 };
 async function createWorkspace(context, name, base, noFetch, options = {}) {
     if (name.startsWith("-") ||
@@ -29,8 +27,7 @@ async function createWorkspace(context, name, base, noFetch, options = {}) {
         throw new Error(`Invalid workspace name: ${name}`);
     git(context.repo, "check-ref-format", "--branch", name);
     return locked(path.join(context.store.root, CREATE_LOCK), LOCK_FILE, async () => {
-        const directoryName = options.directoryName ?? name;
-        const destination = path.resolve(context.managedDir, directoryName);
+        const destination = path.resolve(context.managedDir, name);
         if (!inside(destination, context.managedDir) ||
             canonical(destination) !== destination)
             throw new Error("Workspace path must stay inside the managed directory without symlinks");
@@ -41,7 +38,7 @@ async function createWorkspace(context, name, base, noFetch, options = {}) {
             const [root, branch] = context.store.worktree(registered.worktree);
             if (branch !== name)
                 throw new Error("Workspace branch changed during selection; retry");
-            return { path: root, name: directoryName, branch, created: false };
+            return { path: root, name, branch, created: false };
         }
         if (fs.existsSync(destination))
             throw new Error(`Workspace path already exists: ${destination}`);
@@ -83,7 +80,7 @@ async function createWorkspace(context, name, base, noFetch, options = {}) {
         git(context.repo, "worktree", "add", ...creationArgs);
         return {
             path: destination,
-            name: directoryName,
+            name,
             branch: name,
             created: true,
         };
@@ -92,7 +89,7 @@ async function createWorkspace(context, name, base, noFetch, options = {}) {
 export async function main(argv) {
     const separator = argv.indexOf("--");
     const forwarded = separator < 0 ? [] : argv.slice(separator + 1);
-    const { values, positionals } = args(separator < 0 ? argv : argv.slice(0, separator), [...contextOptions, "base", "branch", "workspace", "agent", "output-path"], ["create", "no-fetch", "setup", "dry-run"], { create: "c", base: "b" });
+    const { values, positionals } = args(separator < 0 ? argv : argv.slice(0, separator), [...contextOptions, "base", "workspace", "agent", "output-path"], ["create", "no-fetch", "setup", "dry-run"], { create: "c", base: "b" });
     const context = commandContext(values);
     const [command, ...names] = positionals;
     const allowedOptions = COMMAND_OPTIONS[command];
@@ -101,10 +98,8 @@ export async function main(argv) {
     for (const option of Object.keys(values))
         if (!contextOptions.includes(option) && !allowedOptions.includes(option))
             throw new Error(`--${option} is not supported by rl ${command}`);
-    if (command === "switch" &&
-        !values.create &&
-        (values.base || values["no-fetch"]))
-        throw new Error("--base and --no-fetch require --create with rl switch");
+    if (command === "switch" && !values.create && values.base)
+        throw new Error("--base requires --create with rl switch");
     const selector = typeof values.workspace === "string" ? values.workspace : undefined;
     if (forwarded.length &&
         command !== "exec" &&
@@ -132,7 +127,7 @@ export async function main(argv) {
             console.log(file);
         }
         else
-            throw new Error("Usage: rl config show|init");
+            throw new Error("Usage: rl setup show|init");
         return 0;
     }
     if (command === "exec") {
@@ -159,35 +154,26 @@ export async function main(argv) {
             });
         });
     }
-    if (!["switch", "new", "open"].includes(command))
-        throw new Error("Unknown workspace workflow command");
-    arity(names, command === "open" ? 0 : 1);
-    const selectedBranch = values.branch ?? (command === "open" ? values.base : undefined);
-    if (command === "open" && typeof selectedBranch !== "string")
-        throw new Error("Usage: rl open --branch <branch>");
+    arity(names, 1);
     const agent = typeof values.agent === "string" ? values.agent : undefined;
     if (agent && !SUPPORTED_AGENTS.has(agent))
         throw new Error("Agent must be codex or claude");
-    const base = command !== "open" && typeof values.base === "string"
-        ? values.base
-        : context.defaultBase;
-    const creating = !!values.create || command === "new" || command === "open";
-    const branch = typeof selectedBranch === "string"
-        ? selectedBranch.replace(/^origin\//, "")
-        : names[0];
-    const target = creating
-        ? await createWorkspace(context, branch, base, !!values["no-fetch"], command === "switch"
-            ? {}
-            : {
-                reuseExisting: true,
-                ...(command === "open"
-                    ? {
-                        directoryName: branch.replaceAll("/", "-"),
-                        requireBranch: true,
-                    }
-                    : {}),
-            })
-        : resolveWorkspace(context, names[0]);
+    const base = typeof values.base === "string" ? values.base : context.defaultBase;
+    let target;
+    if (values.create) {
+        target = await createWorkspace(context, names[0], base, !!values["no-fetch"]);
+    }
+    else {
+        try {
+            target = resolveWorkspace(context, names[0]);
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                !error.message.startsWith("Workspace not found:"))
+                throw error;
+            target = await createWorkspace(context, names[0].replace(/^origin\//, ""), base, !!values["no-fetch"], { reuseExisting: true, requireBranch: true });
+        }
+    }
     await context.store.adopt(target.path, base);
     if (values.setup) {
         const code = await locked(path.join(context.store.root, SETUP_LOCK), LOCK_FILE, () => {

package/lib/entry.zsh

@@ -0,0 +1,54 @@
+#!/bin/zsh -f
+emulate -L zsh
+readonly rl_home="${${(%):-%x}:A:h:h}"
+if [[ "$1" == __hook ]]; then
+  # Hooks resolve the installed CLI on PATH, not a version-specific package path.
+  # Their explicit repository/state arguments must not be replaced by user config.
+  shift
+  exec node "$rl_home/dist/cli.js" state "$@"
+fi
+if [[ "$1" == --version || "$1" == -V ]]; then
+  exec node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version' "$rl_home/package.json"
+fi
+if [[ "$1" == setup && "$2" == shell ]]; then
+  if (( $# == 2 )); then
+    exec node "$rl_home/dist/help.js" setup shell
+  fi
+  for argument in "$@"; do
+    [[ "$argument" == -- ]] && break
+    if [[ "$argument" == --help || "$argument" == -h ]]; then
+      exec node "$rl_home/dist/help.js" "$@"
+    fi
+  done
+  if [[ "$3" != zsh && "$3" != bash || $# != 3 ]]; then
+    print -u2 'Usage: rl setup shell <zsh|bash>'
+    exit 1
+  fi
+  if [[ "$3" == zsh ]]; then
+    print -r -- "source ${(q)rl_home}/shell/rl.zsh"
+  else
+    print -r -- "_rl_executable=${(qq)rl_home}/bin/rl"
+    cat <<'BASH'
+rl() {
+  local destination_file destination result previous="$PWD"
+  local -a arguments=("$@")
+  if [[ "$1" == switch && "${2:-}" == - ]]; then
+    [[ -n "${RL_PREVIOUS_WORKSPACE:-}" ]] || { printf '%s\n' 'No previous workspace in this shell' >&2; return 1; }
+    arguments[1]="$RL_PREVIOUS_WORKSPACE"
+  fi
+  destination_file=$(mktemp "${TMPDIR:-/tmp}/rl-shell.XXXXXXXX") || return 1
+  if RL_SHELL_OUTPUT="$destination_file" command "$_rl_executable" "${arguments[@]}"; then result=0; else result=$?; fi
+  destination=$(cat -- "$destination_file")
+  rm -f -- "$destination_file"
+  if [[ -n "$destination" ]]; then
+    builtin cd -- "$destination" || return 1
+    RL_PREVIOUS_WORKSPACE="$previous"
+  fi
+  return "$result"
+}
+BASH
+  fi
+  exit 0
+fi
+source "$rl_home/lib/rl.zsh" || exit 1
+_rl_main "$@"

package/lib/rl.zsh

@@ -24,6 +24,12 @@ _rl_change_directory() {
     print -rn -- "$PWD" > "$RL_SHELL_OUTPUT"
   else
     print -r -- "$PWD"
+    if [[ -t 1 && -t 2 ]]; then
+      case "${SHELL:t}" in
+        zsh|bash) print -u2 -r -- "Enable directory switching: eval \"\$(rl setup shell ${SHELL:t})\"" ;;
+        *) print -u2 'Enable directory switching with shell integration: rl help setup shell' ;;
+      esac
+    fi
   fi
 }
 
@@ -57,12 +63,12 @@ _rl_main() {
       return
     fi
   done
-  if (( ${#help_args} == 1 )) && [[ "$help_args[1]" == (agent|workflow|policy|repo|git|notes|session|config) ]]; then
+  if (( ${#help_args} == 1 )) && [[ "$help_args[1]" == (agent|workflow|policy|repo|git|notes) ]]; then
     _rl_help "${help_args[@]}"
     return
   fi
 
-  # Canonical command families; older spellings remain compatibility aliases.
+  # Translate public command families to their internal handlers.
   # Preserve a leading repository selector while normalizing the public command.
   local -a routing_prefix=()
   if [[ "$1" == --repo ]]; then
@@ -72,7 +78,23 @@ _rl_main() {
     routing_prefix=("$1")
     shift
   fi
+  case "$1" in
+    new|open|instances|merge|clean|summary|handoff|mcp|session|context|progress|config|adopt|init)
+      print -u2 -r -- "Unknown command: $1"
+      print -u2 'Run rl help for available commands.'
+      return 1 ;;
+    status)
+      if (( ${argv[(Ie)--all]} || ${argv[(Ie)--list]} )); then
+        print -u2 'Use rl list for workspace overviews.'
+        return 1
+      fi ;;
+  esac
   case "$1:$2" in
+    setup:dependencies|setup:install)
+      local setup_module=dependencies
+      [[ "$2" == install ]] && setup_module=install
+      command node "${${functions_source[_rl_main]}:A:h:h}/dist/$setup_module.js" "${@:3}"
+      return ;;
     git:merge) argv=("$2" "${@:3}") ;;
     agent:sessions) argv=(session list "${@:3}") ;;
     agent:save) argv=(session save "${@:3}") ;;
@@ -81,9 +103,10 @@ _rl_main() {
     storage:clean) argv=(clean "${@:3}") ;;
     setup:init|setup:show) argv=(config "$2" "${@:3}") ;;
     setup:adopt) argv=(adopt "${@:3}") ;;
+    setup:mcp) argv=(mcp-setup "${@:3}") ;;
     setup:run) argv=(setup "${@:3}") ;;
     setup:shell)
-      command "${${functions_source[_rl_main]}:A:h:h}/bin/rl" init "${@:3}"
+      command "${${functions_source[_rl_main]}:A:h:h}/bin/rl" setup shell "${@:3}"
       return ;;
     notes:summary) argv=(summary "${@:3}") ;;
     notes:show|notes:path|notes:set|notes:append)
@@ -209,13 +232,19 @@ _rl_main() {
       --default-base "$default_base" "$@"
     return
   fi
-  if [[ "$command" == pr && ( "$2" == checks || "$2" == checkout ) ]]; then
+  if [[ "$command" == pr && "$2" == checkout ]]; then
     command node "${${functions_source[_rl_main]}:A:h:h}/dist/cli.js" pr \
       --repo "$repo_root" --state-dir "$state_dir" --base-dir "$base_dir/$repo_name" \
       --default-base "$default_base" "$@"
     return
   fi
   case "$command" in
+    mcp-setup)
+      shift
+      command node "${${functions_source[_rl_main]}:A:h:h}/dist/cli.js" mcp-setup \
+        --repo "$repo_root" --state-dir "$state_dir" --base-dir "$base_dir/$repo_name" \
+        --default-base "$default_base" "$@"
+      return ;;
     storage|clean)
       command node "${${functions_source[_rl_main]}:A:h:h}/dist/cli.js" storage \
         --repo "$repo_root" --state-dir "$state_dir" --base-dir "$base_dir/$repo_name" \
@@ -260,13 +289,13 @@ _rl_main() {
       command node "${${functions_source[_rl_main]}:A:h:h}/dist/cli.js" summary \
         --repo "$repo_root" --state-dir "$state_dir" --default-base "$default_base" "$@"
       return ;;
-    adopt|doctor|status|instances|resume|session|context|progress|pr)
+    adopt|doctor|status|resume|session|context|progress|pr)
       _rl_state "$@"
       return ;;
   esac
 
   case "$command" in
-    switch|new|open|continue)
+    switch|continue)
       if [[ "$command" == switch && "$2" == - ]]; then
         [[ -n "${RL_PREVIOUS_WORKSPACE:-}" ]] || { print -u2 'No previous workspace in this shell'; return 1; }
         argv[2]="$RL_PREVIOUS_WORKSPACE"