@akira-tl/forgerelay 0.2.6 → 0.3.0

package/dist/mcp/server-instructions.js

@@ -14,57 +14,42 @@ export const toolNames = {
     writeStdin: "write_stdin",
 };
 export function buildShellMutationPolicy() {
-    return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. Never use shell commands to modify security- or privilege-sensitive operating-system files or credential material such as /etc/sudoers, /etc/passwd, /etc/shadow, PAM or authentication policy, SSH private keys, or equivalent privileged system files. Modify configuration files through shell only when the user's request explicitly calls for that configuration change; do not infer permission merely because changing configuration would be convenient.";
+    return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. They may also perform external device or hardware mutations when the user's current request explicitly asks for the actual device-changing operation, including firmware flashing or equivalent persistent device updates; do not infer such authorization from a check, audit, probe, backup, verification, dry-run, or build-only request. Never use shell commands to modify security- or privilege-sensitive operating-system files or credential material such as /etc/sudoers, /etc/passwd, /etc/shadow, PAM or authentication policy, SSH private keys, or equivalent privileged system files. Modify configuration files through shell only when the user's request explicitly calls for that configuration change; do not infer permission merely because changing configuration would be convenient.";
 }
-export function buildServerInstructions(config, context = {}) {
-    return joinInstructions(capabilityContractInstructions(config, context), selectedWorkflowInstructions(config), config.appendInstructions);
+export function buildServerInstructions(config) {
+    return joinInstructions(capabilityContractInstructions(config), selectedWorkflowInstructions(config), config.appendInstructions);
 }
 export function buildToolDescriptions(config) {
     const skillCapability = config.skillsEnabled
-        ? " Advertised skill paths may be outside the workspace; only advertised SKILL.md files and files under already-loaded skill directories are readable."
+        ? " Advertised skill paths may also be outside the workspace."
         : "";
     const shellSurface = config.toolMode === "minimal"
         ? ` In minimal tool mode, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} are disabled, so shell commands may be used for equivalent search and directory inspection.`
         : "";
-    const shellMutationPolicy = buildShellMutationPolicy();
     return {
-        read: `Read a file inside an open workspace or the OS temp directory. Instruction files returned by ${toolNames.openWorkspace} and advertised skill files are also readable when applicable.${skillCapability} Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        read: `Read a file inside an open workspace or the OS temp directory. Instruction files and advertised capability guides returned by ${toolNames.openWorkspace} are also readable when applicable.${skillCapability} Only advertised entry files and files under already-loaded advertised directories are readable outside the normal roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         edit: `Edit one file inside an open workspace or the OS temp directory by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. ForgeRelay waits up to 300 seconds for bash, then returns a running process with a processId without killing it; use ${toolNames.writeStdin} with that processId to poll, keep waiting, interact, or send Ctrl-C. Completed background commands are also reported with a later tool result for the same workspaceId. ${shellMutationPolicy} Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
+        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. ForgeRelay waits up to 300 seconds, then returns a processId for a still-running command; use ${toolNames.writeStdin} to poll, interact, wait, or send Ctrl-C. Completed background commands may be reported later for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
-function capabilityContractInstructions(config, context) {
-    const workspaceLifecycle = config.toolMode === "codex"
-        ? `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Keep the workspaceId returned for this conversation stable. Different conversations normally receive separate logical workspaceIds even when they point at the same physical checkout or worktree; pass an existing workspaceId to ${toolNames.openWorkspace} only when the user wants to resume that logical workspace in this conversation. Only request a new logical workspace when the user explicitly asks. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`
-        : `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Keep the workspaceId returned for this conversation stable for later file, search, edit, write, rename, delete, show-changes, shell, and process-polling tools. Different conversations normally receive separate logical workspaceIds even when they point at the same physical checkout or worktree; pass an existing workspaceId to ${toolNames.openWorkspace} only when the user wants to resume that logical workspace in this conversation. Only request a new logical workspace when the user explicitly asks. If ${toolNames.openWorkspace} reports logical workspaces idle for more than two days, tell the user each workspaceId and let them decide whether to resume it or explicitly clean it up with ${toolNames.closeWorkspace}; do not close it automatically. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`;
-    const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in availableAgentsFiles, use ${toolNames.read} to inspect that instruction file and follow it.`;
+function capabilityContractInstructions(config) {
+    const staleWorkspacePolicy = config.toolMode === "codex"
+        ? ""
+        : ` If ${toolNames.openWorkspace} reports logical workspaces idle for more than two days, let the user choose whether to resume or close them with ${toolNames.closeWorkspace}; never close them automatically.`;
+    const workspaceLifecycle = `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Reuse the workspaceId returned by ${toolNames.openWorkspace} for this conversation; resume another logical workspaceId only when the user wants that workspace, and request a new logical workspace only when explicitly asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} releases a logical workspace; ${toolNames.closeWorktree} finalizes a managed worktree. Read the managed-worktrees capability guide for advanced worktree lifecycle and failure semantics.`;
+    const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Read an availableAgentsFiles path before working under it.`;
+    const capabilityGuides = `When ${toolNames.openWorkspace} returns capability guides, use ${toolNames.read} to load only a task-relevant guide; do not preload all guides.`;
     const skills = config.skillsEnabled
-        ? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, but ${toolNames.read} only permits advertised SKILL.md files and files under already-loaded skill directories.`
+        ? `When a task matches an available skill from ${toolNames.openWorkspace}, read its advertised path before proceeding. Outside normal file roots, ${toolNames.read} permits only advertised entry files and files under already-loaded advertised directories.`
         : "";
-    const toolSurface = toolSurfaceInstructions(config);
     const shellMutationPolicy = buildShellMutationPolicy();
     const hooks = "When a ForgeRelay tool result reports Hook results, tell the user which meaningful hooks ran and whether they passed or blocked the operation. Do not claim the requested operation succeeded when a blocking hook prevented it.";
-    const artifact = config.artifactsEnabled && context.artifactDownloadSupported
-        ? "When the user supplies or generates a file that is not present on the ForgeRelay host, use download_artifact with its native file value, the existing workspace ID, and a suitable relative destination path chosen from the user's request and project structure. The tool refuses to overwrite an existing destination and returns the normalized workspace-relative path. Use normal workspace tools when explicit inspection, replacement, movement, renaming, or deletion is needed. Do not recreate binary files with write/edit calls or place signed URLs, native file objects, base64 content, or invented host paths in shell commands or logs."
-        : "";
-    const showChanges = config.widgets === "changes"
-        ? "If the turn successfully modifies files by creating, editing, overwriting, deleting, moving, or applying patches, call show_changes exactly once for that workspace after the final related file change and before your final response so the user can inspect the aggregate diff for that turn. Do not call it after every individual file change; do not skip it because individual file-change tools already returned diffs."
-        : "";
-    return joinInstructions(workspaceLifecycle, agents, skills, toolSurface, shellMutationPolicy, hooks, artifact, showChanges);
-}
-function toolSurfaceInstructions(config) {
-    if (config.toolMode === "codex") {
-        return `In codex tool mode, workspace file and command operations use ${toolNames.read}, ${toolNames.rename}, ${toolNames.delete}, apply_patch, exec_command, and ${toolNames.writeStdin}.`;
-    }
-    if (config.toolMode === "full") {
-        return `In full tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are available alongside the core workspace tools. ${toolNames.writeStdin} is available for running bash processes.`;
-    }
-    return `In minimal tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are disabled; the core workspace tools remain available, including ${toolNames.writeStdin} for running bash processes.`;
+    return joinInstructions(workspaceLifecycle, agents, capabilityGuides, skills, shellMutationPolicy, hooks);
 }
 function selectedWorkflowInstructions(config) {
     if (config.workflowInstructions === false)

package/dist/server.js

@@ -14,6 +14,7 @@ import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@mode
 import express from "express";
 import * as z from "zod/v4";
 import { applyPatch } from "./apply-patch.js";
+import { buildCapabilityFingerprint } from "./capabilities.js";
 import { deletePath, renamePath } from "./file-mutations.js";
 import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
 import { loadConfig } from "./config.js";
@@ -112,6 +113,17 @@ const workspaceSkillOutputSchema = z.object({
     description: z.string(),
     path: z.string(),
 });
+const capabilityFingerprintOutputSchema = z.object({
+    version: z.string(),
+    toolMode: z.enum(["minimal", "full", "codex"]),
+    capabilities: z.array(z.string()),
+});
+const capabilityGuideOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    whenToRead: z.string(),
+    path: z.string(),
+});
 const workspaceAgentsFileOutputSchema = z.object({
     path: z.string(),
     content: z.string(),
@@ -154,7 +166,7 @@ function sendJsonRpcError(res, status, code, message) {
 }
 function requestLogFields(req, config) {
     return {
-        ip: requestIp(req, config.logging.trustProxy),
+        ip: requestIp(req),
         host: req.header("host"),
         userAgent: req.header("user-agent"),
         origin: req.header("origin"),
@@ -639,9 +651,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         version: FORGERELAY_VERSION,
         description: "Secure local coding workspace for MCP clients. Provides workspace-scoped file, search, edit, write, and shell tools.",
     }, {
-        instructions: buildServerInstructions(config, {
-            artifactDownloadSupported: isArtifactDownloadSupportedPlatform(),
-        }),
+        instructions: buildServerInstructions(config),
     });
     const currentWorkspaceAppUri = currentWorkspaceAppIdentity().uri;
     const workspaceAppResourceMetadata = {
@@ -660,7 +670,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     }, async (uri, _variables, extra) => readWorkspaceAppResource(config, uri.toString(), extra.sessionId));
     registerAppTool(server, "open_workspace", {
         title: "Open workspace",
-        description: "Open or resume a local coding workspace. A conversation keeps a stable workspaceId for a project, while different conversations normally receive different logical workspaceIds that may point at the same physical checkout or worktree. Pass workspaceId to explicitly resume an existing logical workspace in this conversation. Default to checkout mode and only use mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Workspaces idle for more than two days are reported for user-directed cleanup or resumption.",
+        description: "Open or resume a local coding workspace. Reuse the returned workspaceId for later calls. Default to checkout; use mode=\"worktree\" only when the user explicitly requests isolated or parallel Git work. Every call returns a capability fingerprint; bootstrap calls also expose project context, skills, and capability guides when needed.",
         inputSchema: {
             path: z
                 .string()
@@ -724,6 +734,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 targetBranch: z.string().optional(),
                 managed: z.boolean(),
             })),
+            capabilityFingerprint: capabilityFingerprintOutputSchema,
+            capabilityGuides: z.array(capabilityGuideOutputSchema).optional(),
             agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
             availableAgentsFiles: z.array(workspaceAvailableAgentsFileOutputSchema).optional(),
             skills: z.array(workspaceSkillOutputSchema).optional(),
@@ -747,6 +759,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         });
         const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
         const staleWorkspaces = await workspaces.listStaleWorkspaces(workspace);
+        const capabilityFingerprint = buildCapabilityFingerprint(config, FORGERELAY_VERSION, {
+            artifactDownloadSupported: isArtifactDownloadSupportedPlatform(),
+        });
         if (config.widgets === "changes") {
             await reviewCheckpoints.initializeWorkspace({
                 workspaceId: workspace.id,
@@ -760,6 +775,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             description: skill.description,
             path: formatPathForPrompt(skill.filePath),
         }));
+        const capabilityGuides = workspace.capabilityGuides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        }));
         const cardAgentProviders = config.subagents ? localAgentProviders : [];
         const cardAgents = workspace.agentProfiles.map((profile) => {
             const summary = summarizeLocalAgentProfile(profile);
@@ -778,13 +799,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             path: formatAgentsPath(file.path, workspace.root),
         }));
         const visibleSkills = includeBootstrapContext ? cardSkills : [];
+        const visibleCapabilityGuides = includeBootstrapContext ? capabilityGuides : [];
         const visibleAgentProviders = includeBootstrapContext ? cardAgentProviders : [];
         const visibleAgents = includeBootstrapContext ? cardAgents : [];
         const loadedAgentsFiles = includeBootstrapContext ? cardAgentsFiles : [];
         const availableAgentsFileOutputs = includeBootstrapContext ? cardAvailableAgentsFiles : [];
         const cardInstruction = config.skillsEnabled
-            ? "Use this workspaceId in all subsequent tool calls for this project. Default to the user's checkout; only create a worktree when the user explicitly requests isolated or parallel work. Managed worktrees are branch-backed. When a managed worktree task is complete and verified, close it with close_worktree so ForgeRelay can commit, fast-forward the target branch when safe, and clean up the worktree. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file. When a task matches an available skill in skills, read its path before proceeding."
-            : "Use this workspaceId in all subsequent tool calls for this project. Default to the user's checkout; only create a worktree when the user explicitly requests isolated or parallel work. Managed worktrees are branch-backed. When a managed worktree task is complete and verified, close it with close_worktree so ForgeRelay can commit, fast-forward the target branch when safe, and clean up the worktree. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file.";
+            ? "Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches an available skill or capability guide, read its advertised path before proceeding."
+            : "Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches a capability guide, read its advertised path before proceeding.";
         const instruction = workspaceReused
             ? includeBootstrapContext
                 ? [
@@ -795,7 +817,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 : [
                     `Workspace already open as ${workspace.id}.`,
                     "Reuse this workspaceId for subsequent tool calls. This is the same directory previously opened in this conversation.",
-                    "Continue following the project instructions, nested instruction files, skills, agent profiles, and diagnostics previously provided for this workspace. They remain active and are not repeated here.",
+                    "Continue following the project instructions, nested instruction files, skills, capability guides, agent profiles, and diagnostics previously provided for this workspace. They remain active and are not repeated here.",
                 ].join("\n\n")
             : workspace.mode === "worktree"
                 ? "Use this workspaceId for subsequent tool calls. Follow the project instructions, nested instruction files, skills, agent profiles, and diagnostics returned for this isolated worktree."
@@ -820,6 +842,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     visibleSkills.length > 0
                         ? `Available skills: ${visibleSkills.map((skill) => skill.name).join(", ")}`
                         : undefined,
+                    visibleCapabilityGuides.length > 0
+                        ? `Capability guides: ${visibleCapabilityGuides.map((guide) => guide.name).join(", ")}`
+                        : undefined,
                     visibleAgentProviders.some((provider) => provider.available)
                         ? `Available subagent providers: ${visibleAgentProviders.filter((provider) => provider.available).map((provider) => provider.name).join(", ")}`
                         : undefined,
@@ -835,6 +860,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     staleWorkspaces.length > 0
                         ? `Idle logical workspaces for this same physical workspace (>2 days): ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. Tell the user these are available to resume or explicitly close; do not clean them up automatically.`
                         : undefined,
+                    `ForgeRelay ${capabilityFingerprint.version} capabilities: ${capabilityFingerprint.capabilities.join(", ")}`,
                     instruction,
                 ].filter(Boolean).join("\n"),
             },
@@ -861,6 +887,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     worktree: workspace.worktree,
                     worktrees: knownWorktrees,
                     staleWorkspaces,
+                    capabilityFingerprint,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
                     skills: cardSkills,
@@ -885,8 +912,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 worktree: workspace.worktree,
                 worktrees: knownWorktrees,
                 staleWorkspaces,
+                capabilityFingerprint,
                 ...(includeBootstrapContext
                     ? {
+                        capabilityGuides: visibleCapabilityGuides,
                         agentsFiles: loadedAgentsFiles,
                         availableAgentsFiles: availableAgentsFileOutputs,
                         skills: visibleSkills,
@@ -901,7 +930,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close logical workspace",
-        description: "Release one logical ForgeRelay workspaceId after the user explicitly chooses to clean it up. This never deletes checkout files. A worktree handle can be released only when another logical handle still anchors the same physical worktree; use close_worktree to finalize and remove the last managed worktree. Running or unconsumed background processes prevent closure.",
+        description: "Release one logical workspaceId after the user chooses cleanup. This does not delete checkout files. Use close_worktree to finalize and remove a managed worktree. Running or unconsumed processes prevent closure.",
         inputSchema: {
             workspaceId: z.string().describe("Logical workspace ID to release."),
         },
@@ -929,7 +958,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorktree, {
         title: "Close worktree",
-        description: "Finish a managed ForgeRelay worktree after its task has been completed and verified. ForgeRelay commits any remaining worktree changes, fast-forwards the original target branch only when the source checkout is clean and the histories have not diverged, then removes the worktree and its forgerelay/* branch. If safe fast-forward is not possible, the source checkout is left out of a merge-conflict state and the worktree is preserved.",
+        description: "Finalize a managed worktree after its task is complete and verified. ForgeRelay may commit remaining changes, integrate the target branch when safe, and clean up the managed worktree. Read the managed-worktrees capability guide for advanced close, safety, and failure semantics.",
         inputSchema: {
             workspaceId: z
                 .string()
@@ -1010,8 +1039,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             path: z
                 .string()
                 .describe(config.skillsEnabled
-                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill path from open_workspace skills, including a ~/... home-relative path."
-                : "File path to read, relative to the workspace root or absolute inside the OS temp directory."),
+                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill or capability-guide path from open_workspace, including a ~/... home-relative path."
+                : "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised capability-guide path from open_workspace."),
             offset: z
                 .number()
                 .int()
@@ -1846,7 +1875,7 @@ export function createServer(config = loadConfig(), options = {}) {
     }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
     transportCleanupTimer.unref();
     if (config.logging.trustProxy) {
-        app.set("trust proxy", true);
+        app.set("trust proxy", 1);
     }
     app.use((req, res, next) => {
         const requestId = randomUUID();

package/dist/skills.js

@@ -1,27 +1,16 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { markAdvertisedFileSourceActivated, resolveAdvertisedFileReadPath, } from "./advertised-files.js";
 import { loadSkills, } from "@earendil-works/pi-coding-agent";
-import { expandHomePath, isPathInsideRoot } from "./roots.js";
+import { expandHomePath } from "./roots.js";
 const SUBAGENT_DELEGATION_NAME = "subagent-delegation";
-const SUBAGENT_DELEGATION_SKILL = join(SUBAGENT_DELEGATION_NAME, "SKILL.md");
-function bundledSkillsDir() {
-    return fileURLToPath(new URL("../skills", import.meta.url));
-}
-function hasSubagentDelegationSkill(skillDir) {
-    return existsSync(join(skillDir, SUBAGENT_DELEGATION_SKILL));
-}
 export function effectiveSkillPaths(config, cwd) {
-    const bundledSkills = bundledSkillsDir();
     const defaultPathCandidates = [
         join(homedir(), ".agents", "skills"),
         resolve(cwd, ".agents", "skills"),
         config.devspaceSkillsDir,
         join(config.agentDir, "skills"),
-        config.subagents && !hasSubagentDelegationSkill(config.devspaceSkillsDir)
-            ? bundledSkills
-            : undefined,
     ];
     const defaultPaths = defaultPathCandidates.filter((path) => path !== undefined && existsSync(path));
     const seen = new Set();
@@ -57,25 +46,17 @@ export function loadWorkspaceSkills(config, cwd) {
     };
 }
 export function resolveSkillReadPath(skills, activatedSkillDirs, inputPath) {
-    const absolutePath = resolve(expandHomePath(inputPath));
-    for (const skill of skills) {
-        const skillFilePath = resolve(skill.filePath);
-        if (absolutePath === skillFilePath) {
-            return { absolutePath, skill, isSkillFile: true };
-        }
-    }
-    for (const skill of skills) {
-        const baseDir = resolve(skill.baseDir);
-        if (!activatedSkillDirs.has(baseDir))
-            continue;
-        if (!isPathInsideRoot(absolutePath, baseDir))
-            continue;
-        return { absolutePath, skill, isSkillFile: false };
-    }
-    return undefined;
+    const resolution = resolveAdvertisedFileReadPath(skills, activatedSkillDirs, inputPath);
+    if (!resolution)
+        return undefined;
+    return {
+        absolutePath: resolution.absolutePath,
+        skill: resolution.source,
+        isSkillFile: resolution.isEntryFile,
+    };
 }
 export function markSkillActivated(activatedSkillDirs, skill) {
-    activatedSkillDirs.add(resolve(skill.baseDir));
+    markAdvertisedFileSourceActivated(activatedSkillDirs, skill);
 }
 export function formatPathForPrompt(path) {
     const home = resolve(homedir());

package/dist/workspaces.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { loadCapabilityGuides, markCapabilityGuideActivated, resolveCapabilityGuideReadPath, } from "./capabilities.js";
 import { HookRunner } from "./hooks.js";
 import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
 import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
@@ -548,8 +549,10 @@ export class WorkspaceRegistry {
                 }
                 : undefined,
             ...this.loadSkillsForWorkspace(root),
+            capabilityGuides: loadCapabilityGuides(this.config),
             agentProfiles: [],
             activatedSkillDirs: new Set(),
+            activatedCapabilityGuideDirs: new Set(),
         };
         if (touch)
             this.store?.touchSession(session.id);
@@ -582,6 +585,14 @@ export class WorkspaceRegistry {
                     skillRead,
                 };
             }
+            const capabilityGuideRead = resolveCapabilityGuideReadPath(workspace.capabilityGuides, workspace.activatedCapabilityGuideDirs, inputPath);
+            if (capabilityGuideRead) {
+                return {
+                    absolutePath: capabilityGuideRead.absolutePath,
+                    readRoots: [workspace.root, capabilityGuideRead.guide.baseDir],
+                    capabilityGuideRead,
+                };
+            }
             try {
                 return {
                     absolutePath: resolveAllowedPath(inputPath, workspace.root, [tmpdir()]),
@@ -597,6 +608,9 @@ export class WorkspaceRegistry {
         if (readPath.skillRead?.isSkillFile) {
             markSkillActivated(workspace.activatedSkillDirs, readPath.skillRead.skill);
         }
+        if (readPath.capabilityGuideRead?.isGuideFile) {
+            markCapabilityGuideActivated(workspace.activatedCapabilityGuideDirs, readPath.capabilityGuideRead.guide);
+        }
     }
     resolveWorkingDirectory(workspace, workingDirectory) {
         const directory = workingDirectory ? this.resolvePath(workspace, workingDirectory) : workspace.root;
@@ -631,8 +645,10 @@ export class WorkspaceRegistry {
             sourceRoot: input.sourceRoot,
             worktree: input.worktree,
             ...this.loadSkillsForWorkspace(input.root),
+            capabilityGuides: loadCapabilityGuides(this.config),
             agentProfiles: await loadLocalAgentProfiles(this.config, input.root),
             activatedSkillDirs: new Set(),
+            activatedCapabilityGuideDirs: new Set(),
         };
         this.store?.createSession({
             id: workspace.id,

package/docs/chatgpt-coding-workflow.md

@@ -9,14 +9,14 @@ checkout.
 `open_workspace` returns a `workspaceId`. Continue using that ID for later tools
 in the same directory.
 
-Workspace identity follows the canonical opened directory rather than the
-conversation/request identity. Reopening the same checkout reuses the same
-active workspace even from another conversation. Conversation metadata is used
-only to decide whether bootstrap context such as project instructions should be
-repeated to that conversation.
+`workspaceId` is a logical conversation handle, not the physical-directory
+identity. Reopening the same checkout in the same conversation keeps that
+logical ID stable. A different conversation normally receives a different
+`workspaceId` even when it points at the same checkout or worktree; pass an
+existing ID explicitly when the user wants to resume that logical workspace.
 
-A Git worktree directory is a separate workspace identity from its source
-checkout.
+A Git worktree directory is a separate physical workspace target from its source
+checkout, and each conversation can still have its own logical handle for it.
 
 ## Checkout-first behavior
 
@@ -108,6 +108,37 @@ being injected eagerly. Read the relevant nested file before working under that
 `FORGERELAY_AGENT_DIR` is not an instruction source; it remains only a compatibility
 skill-discovery path.
 
+## MCP capability loading
+
+ForgeRelay keeps callable MCP tools and explanatory capability documentation
+separate. `tools/list` remains the source of truth for what the current server
+actually exposes; 0.3 does not hide callable tools behind documentation.
+
+`open_workspace` adds two lightweight discovery surfaces:
+
+- `capabilityFingerprint` is returned on every open/resume and includes the
+  ForgeRelay version, active tool mode, and stable semantic capability names;
+- `capabilityGuides` is returned with bootstrap context and contains compact
+  descriptors for ForgeRelay-owned, versioned guides that can be loaded with
+  the normal `read` tool.
+
+Do not preload every capability guide. Read a guide only when the current task
+needs that domain. Built-in guides cover lifecycle Hooks, advanced managed
+worktrees, subagents, artifact/change-review workflows, Host/OAuth/MCP App
+integration, and long-running shell/PTY/process behavior. Optional guides are
+advertised only when their feature is enabled; for example, disabled subagents
+and artifact/change-review features do not add those descriptors to bootstrap
+context. Reopening a workspace in the same Host context does not repeat the
+descriptors, but the previously advertised guides remain valid.
+
+The fingerprint is also a stale-Host-schema diagnostic. If `open_workspace`
+reports a capability such as `filesystem.rename-move` but the Host's current
+MCP tool snapshot does not expose `rename`, the server and Host metadata are out
+of sync. Refresh/reconnect the MCP integration or start a Host context that
+reloads `tools/list`; do not conclude that the running ForgeRelay server lacks
+that capability. ForgeRelay can report its own version/capabilities but cannot
+force the Host to discard a cached tool schema.
+
 ## Agent Skills
 
 ForgeRelay discovers standard Agent Skills from:
@@ -134,7 +165,11 @@ config directory plus:
 ```
 
 The workspace result exposes only compact profile metadata so the host can
-choose a provider/profile without loading full provider launch details.
+choose a provider/profile without loading full provider launch details. Read the
+ForgeRelay-owned `subagents` capability guide when delegation is actually needed;
+0.3 no longer auto-loads the historical bundled `subagent-delegation` Skill for
+new setups. Existing user-authored or previously seeded Skills remain normal
+user configuration and are not deleted.
 
 The current model-facing delegation workflow is:
 
@@ -178,7 +213,8 @@ same workspace ID. The former process `sessionId` remains a deprecated alias in
 
 Experimental `FORGERELAY_TOOL_MODE=codex` provides a smaller Codex-shaped
 surface including direct `rename`/`delete` path mutations alongside `apply_patch`,
-`exec_command`, and `write_stdin`.
+`exec_command`, and `write_stdin`. `rename` is the unified move/rename primitive
+for both files and directories; ForgeRelay does not expose a separate `move` tool.
 
 Workspace IDs are logical conversation handles rather than physical-directory
 identities. The same conversation keeps a stable ID for a project, while another
@@ -193,10 +229,16 @@ be released that way and must be finalized with `close_worktree`.
 Shell commands are allowed to modify ordinary project files when that is a
 natural part of the user's requested development task; ForgeRelay does not apply
 a blanket ban to package managers, generators, formatters, or similar commands
-that write files. The Agent contract still prohibits shell mutation of
-security- or privilege-sensitive operating-system files and credential material,
-and requires an explicit user request before changing configuration files
-through `bash` or `exec_command`.
+that write files. They may also perform external device or hardware mutations
+when the user's current request explicitly asks for the actual device-changing
+operation. A check, audit, probe, backup, verification, dry-run, or build-only
+request does not implicitly authorize a later persistent device write, and
+ForgeRelay does not assume a particular flashing protocol or transport.
+
+The Agent contract still prohibits shell mutation of security- or
+privilege-sensitive operating-system files and credential material, and requires
+an explicit user request before changing configuration files through `bash` or
+`exec_command`.
 
 ## Change review UI
 

package/docs/configuration.md

@@ -123,6 +123,35 @@ MCP clients discover metadata from:
 explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
 also accepted.
 
+The selected mode controls the real `tools/list` surface. ForgeRelay does not
+hide callable tools behind capability documentation. In every mode,
+`open_workspace` returns a `capabilityFingerprint` containing the package
+version, tool mode, and stable semantic capability names. The fingerprint also
+reports enabled optional domains such as subagent profile discovery, native
+artifact download, MCP App UI, or aggregate `show_changes` review when those
+features are actually available; it remains a semantic summary rather than a
+copy of `tools/list`.
+
+Bootstrap responses also return `capabilityGuides`, which are compact descriptors
+for built-in ForgeRelay documentation that the Agent can explicitly load with
+`read` when a task needs that domain. Current built-in domains cover lifecycle
+Hooks, managed worktrees, subagents, artifact/change-review workflows, Host/OAuth/
+MCP App integration, and long-running shell/PTY/process behavior. Optional-domain
+descriptors such as `subagents` and `artifacts-review` are advertised only when
+the corresponding feature is enabled, so disabled features do not add bootstrap
+context.
+
+There is no separate progressive-disclosure configuration switch. Capability
+Guide discovery is built in, while actual tool exposure continues to be
+controlled by `FORGERELAY_TOOL_MODE` and feature-specific settings. If the
+fingerprint reports a capability that is missing from the Host's current tool
+snapshot, treat that as stale Host MCP metadata: reconnect/refresh the integration
+or use a Host context that reloads `tools/list`. The ForgeRelay process cannot
+force a Host to invalidate its cached schema.
+
+`rename` is the canonical move/rename primitive for files and directories; there
+is no separate `move` MCP tool.
+
 Codex-mode commands run without a PTY by default. `tty: true` enables interactive
 programs when the optional `node-pty` dependency is available.
 
@@ -316,7 +345,8 @@ When subagents are enabled, profiles are discovered from:
 - active legacy config directory `~/.devspace/agents/*.md` when reused;
 - project `.devspace/agents/*.md` for migration compatibility.
 
-The bundled `subagent-delegation` skill teaches the current CLI workflow:
+The ForgeRelay-owned `subagents` capability guide teaches the current CLI
+workflow on demand:
 
 ```bash
 forgerelay agents ls
@@ -324,6 +354,11 @@ forgerelay agents run <profile-or-provider-or-id> "<prompt>"
 forgerelay agents show <id>
 ```
 
+0.3 no longer auto-discovers or seeds the package's historical bundled
+`subagent-delegation` Skill for new setups. An existing or user-authored Skill
+with that name remains an ordinary Skill and is still discovered from the normal
+Skill paths when subagents are enabled; ForgeRelay does not delete or rewrite it.
+
 ## Logging
 
 | Variable | Default |
@@ -334,7 +369,7 @@ forgerelay agents show <id>
 | `FORGERELAY_LOG_ASSETS` | `0` |
 | `FORGERELAY_LOG_TOOL_CALLS` | `1` |
 | `FORGERELAY_LOG_SHELL_COMMANDS` | `1` in `pretty`, `0` in `json` |
-| `FORGERELAY_TRUST_PROXY` | `0` |
+| `FORGERELAY_TRUST_PROXY` | auto: `1` only for loopback bind + non-loopback public URL; otherwise `0` |
 
 `pretty` is the human-facing local console format. It uses terminal-aware color,
 short timestamps, workspace-first context, and compact operation results while
@@ -351,6 +386,14 @@ overridden, JSON mode preserves request logging and omits shell command previews
 `FORGERELAY_LOG_REQUESTS` and `FORGERELAY_LOG_SHELL_COMMANDS` always override
 these format-specific defaults when set.
 
+When ForgeRelay binds to loopback (`127.0.0.1`, `::1`, or `localhost`) but is
+configured with a non-loopback public URL, it automatically trusts exactly one
+upstream proxy hop. This matches the normal tunnel/reverse-proxy topology and
+keeps OAuth rate limiting aligned with Express client-IP resolution. Set
+`FORGERELAY_TRUST_PROXY=0` to disable this inference, or `=1` to enable one-hop
+trust explicitly. ForgeRelay never auto-enables proxy trust when binding to
+`0.0.0.0` or another directly reachable interface.
+
 ## Environment-only example
 
 ```bash