@akira-tl/forgerelay 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.1.2] - 2026-09-11
+
+### Fixed
+
+- Clarified Capability discovery so Agents use only `open_workspace.capabilityCatalog` names with the `capability` gateway; semantic `capabilityFingerprint.capabilities` entries and Capability Guide descriptors are no longer presented as callable capability names.
+- Changed Agent Skill collision precedence so a Project's `.agents/skills` definition wins over the same-named global `~/.agents/skills` definition, keeping Project-local workflow customizations authoritative.
+
 ## [1.1.1] - 2026-09-10
 
 ### Added

package/dist/mcp/server/workspace/runtime/workspace-open-presentation.js

@@ -11,6 +11,7 @@ import { redactSkillDiagnosticPaths } from "../../core/schemas.js";
 import { logToolCall, workspaceLogContext } from "../../core/tool-support.js";
 import { buildExecutionShellContext } from "../../../server-instructions.js";
 export const workspaceTaskUsageInstruction = "Use workspace.tasks proactively for work that spans multiple steps or sessions: create or update Tasks to preserve useful next steps and current state, and read its summary when resuming relevant unfinished work. Do not query it mechanically on every open_workspace call.";
+export const capabilityDiscoveryInstruction = "For capability describe/run, use only names present in capabilityCatalog. capabilityFingerprint.capabilities is a semantic feature fingerprint, not a callable registry; capabilityGuides are documentation descriptors, not callable capabilities.";
 export async function presentLocalWorkspaceOpen(options, input, contextData) {
     const { config, forgerelayVersion: FORGERELAY_VERSION, workspaces, workspaceTasks, reviewCheckpoints, capabilityRegistry, subagentProviders, hooks, rememberWorkspacePanelState, } = options;
     const { path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context } = input;
@@ -98,6 +99,7 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
     const workspaceContextInstruction = "For later open_workspace calls, context=\"auto\" avoids repeating unchanged bootstrap context; use context=\"none\" when only the workspace handle/metadata is needed, or context=\"full\" to force a refresh.";
     const workspaceManagementInstruction = [
         "Use open_workspace(action=\"list\") for lightweight Workspace inventory. Use action=\"inspect\" with one known workspaceId for bounded read-only metadata without opening/resuming it. Explicitly open a Workspace before executing or mutating against it, and ask the user before close_workspace cleanup.",
+        capabilityDiscoveryInstruction,
         capabilityCatalog.some((entry) => entry.name === "workspace.tasks")
             ? workspaceTaskUsageInstruction
             : undefined,

package/dist/mcp/server/workspace/runtime/workspace-tools.js

@@ -57,14 +57,14 @@ export function registerWorkspaceAuxiliaryTools(options) {
     });
     registerAppTool(server, toolNames.capability, {
         title: "Use optional capability",
-        description: "Describe or run one optional ForgeRelay capability advertised by open_workspace. Use describe when the capability contract is unfamiliar, then read its advertised guide if needed. Run dispatches only explicitly registered capabilities; it cannot invoke arbitrary shell commands, URLs, or methods.",
+        description: "Describe or run one registered ForgeRelay capability. Only names present in open_workspace.capabilityCatalog are valid for describe/run. capabilityFingerprint.capabilities is a semantic feature fingerprint, not a callable registry, and capabilityGuides are documentation descriptors rather than callable capabilities. Use describe when the capability contract is unfamiliar, then read its advertised guide if needed. Run cannot invoke arbitrary shell commands, URLs, or methods.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
             member: z.string().optional().describe("Required for a Composite Workspace; explicit member name whose capability surface is used."),
             name: z
                 .string()
                 .regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/)
-                .describe("Stable dotted capability name advertised by open_workspace."),
+                .describe("Stable dotted capability name present in open_workspace.capabilityCatalog. Do not use semantic-only names from capabilityFingerprint.capabilities or capabilityGuides."),
             action: z.enum(["describe", "run"]),
             arguments: z
                 .record(z.string(), z.unknown())

package/dist/workspaces/resources/skills.js

@@ -7,8 +7,8 @@ import { expandHomePath, isPathInsideRoot } from "../../mcp/filesystem/roots.js"
 const FRONTMATTER_DELIMITER = "---";
 export function effectiveSkillPaths(config, cwd) {
     const defaultPathCandidates = [
-        join(homedir(), ".agents", "skills"),
         resolve(cwd, ".agents", "skills"),
+        join(homedir(), ".agents", "skills"),
         config.configSkillsDir,
         join(config.agentDir, "skills"),
     ];

package/docs/chatgpt-coding-workflow.md

@@ -201,12 +201,16 @@ gateway rather than each receiving another top-level tool schema.
 `open_workspace` adds lightweight discovery surfaces:
 
 - `capabilityFingerprint` is returned on every open/resume and includes the
-  ForgeRelay version, active tool mode, and stable semantic capability names;
-- `capabilityCatalog` lists currently available registered actions such as
-  `hooks.check`, with compact guide metadata;
+  ForgeRelay version, active tool mode, and stable semantic capability names. It
+  is a feature fingerprint, not a callable registry;
+- `capabilityCatalog` is the callable registry for the `capability` gateway and
+  lists currently available registered actions such as `hooks.check`, with
+  compact guide metadata. Only names present here are valid for
+  `capability(action="describe"|"run")`;
 - `capabilityGuides` is returned with bootstrap context and contains compact
   descriptors for ForgeRelay-owned, versioned guides that can be loaded with
-  the normal `read` tool.
+  the normal `read` tool. Guide names are documentation descriptors, not
+  callable capability names.
 
 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
@@ -228,14 +232,16 @@ force the Host to discard a cached tool schema.
 
 ## Agent Skills
 
-ForgeRelay discovers standard Agent Skills from:
+ForgeRelay discovers standard Agent Skills in precedence order from:
 
-- `~/.agents/skills`
 - project `.agents/skills`
+- `~/.agents/skills`
 - the active ForgeRelay config directory's `skills` folder
 - `FORGERELAY_AGENT_DIR/skills` (defaults to `~/.codex/skills`)
 - paths from `FORGERELAY_SKILL_PATHS`
 
+Same-named collisions use the first source, so project Skills override global Skills.
+
 When a task matches an advertised skill, read its `SKILL.md` before using other
 files in the skill directory.
 

package/docs/configuration.md

@@ -860,14 +860,16 @@ select a global instruction file; its `skills` child is an additional Agent Skil
 | `FORGERELAY_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is included as an additional Skill source. |
 | `FORGERELAY_SKILL_PATHS` | Optional comma-separated additional skill directories. |
 
-Standard Agent Skills are discovered from:
+Standard Agent Skills are discovered in precedence order from:
 
-- `~/.agents/skills`
 - project `.agents/skills`
+- `~/.agents/skills`
 - the active ForgeRelay config directory's `skills` folder
 - `FORGERELAY_AGENT_DIR/skills`
 - paths from `FORGERELAY_SKILL_PATHS`
 
+When the same Skill name appears in more than one source, the first source wins. Project Skills therefore override same-named global `~/.agents/skills` entries, matching ForgeRelay's project-over-global configuration model.
+
 When subagents are enabled, profiles are discovered from:
 
 - the active ForgeRelay config directory's `agents/*.md`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",