@akira-tl/forgerelay 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-08-09
+
+### Changed
+
+- GitHub CI is now release-only: ordinary branch pushes, pull-request updates, and manual dispatches do not start cloud CI; the reusable CI workflow is invoked only by the stable `vX.Y.Z` tag release workflow.
+- Release automation now triggers only for stable `vX.Y.Z` version tags, waits for cloud CI to pass, then publishes; ordinary branch pushes never enter the CI or publication workflows.
+- Global system instructions now come from exactly one configured file, defaulting to `~/.agents/AGENTS.md`; `FORGERELAY_AGENT_DIR` remains a skill-compatibility path rather than an instruction source.
+
+### Fixed
+
+- Symbolic-link system instruction entries now follow their configured target even when the canonical source lives outside the runtime instruction directory.
+- Project instruction aliases that resolve to the same file are loaded once, preventing duplicate `AGENTS.md` context on case-insensitive filesystems such as default macOS and Windows checkouts.
+
 ## [0.1.0] - 2026-08-09
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 **Give MCP coding agents a real local workspace.**
 
 [![npm](https://img.shields.io/npm/v/%40akira-tl%2Fforgerelay?style=flat-square)](https://www.npmjs.com/package/@akira-tl/forgerelay)
-[![CI](https://img.shields.io/github/actions/workflow/status/Akira-TL/forgerelay/ci.yml?style=flat-square&branch=main)](https://github.com/Akira-TL/forgerelay/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/actions/workflow/status/Akira-TL/forgerelay/release.yml?style=flat-square&label=release)](https://github.com/Akira-TL/forgerelay/actions/workflows/release.yml)
 [![License](https://img.shields.io/npm/l/%40akira-tl%2Fforgerelay?style=flat-square)](LICENSE)
 
 ForgeRelay is a self-hosted MCP server that lets ChatGPT and other MCP-capable
@@ -227,9 +227,11 @@ npm run release:major
 npm run release:verify
 ```
 
-Pushing a matching `vX.Y.Z` tag to `Akira-TL/forgerelay` is the publish action.
-GitHub Actions verifies the tagged commit, publishes `@akira-tl/forgerelay` to
-npm, and creates the matching GitHub Release.
+Daily branch pushes do not run cloud CI. When preparing a release, run the full
+local release verification first. Pushing a matching `vX.Y.Z` tag to
+`Akira-TL/forgerelay` is the only cloud CI and publish trigger: GitHub Actions
+runs the reusable multi-platform CI, then publishes `@akira-tl/forgerelay` and
+creates the matching GitHub Release only after CI succeeds.
 
 See [Versioning and Release Management](docs/versioning.md) for the bootstrap and
 Trusted Publishing setup.

package/dist/config.js

@@ -164,6 +164,17 @@ function defaultWorktreeRoot() {
 function defaultAgentDir() {
     return join(homedir(), ".codex");
 }
+function defaultSystemInstructionsPath() {
+    return join(homedir(), ".agents", "AGENTS.md");
+}
+function parseSystemInstructionsPath(value) {
+    if (value === undefined)
+        return resolve(defaultSystemInstructionsPath());
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("FORGERELAY_SYSTEM_INSTRUCTIONS_PATH must be one non-empty path");
+    }
+    return resolve(expandHomePath(value.trim()));
+}
 export function loadConfig(env = process.env) {
     const files = loadForgeRelayFiles(env);
     const host = env.HOST ?? files.config.host ?? "127.0.0.1";
@@ -202,6 +213,7 @@ export function loadConfig(env = process.env) {
             ? files.config.subagents === true
             : parseBoolean(productEnv(env, "SUBAGENTS")),
         agentDir: resolve(expandHomePath(productEnv(env, "AGENT_DIR") ?? files.config.agentDir ?? defaultAgentDir())),
+        systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
         logging: parseLoggingConfig(env),
     };
 }

package/dist/workspaces.js

@@ -1,7 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
 import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
 import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
 import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
@@ -381,21 +380,34 @@ export class WorkspaceRegistry {
         return assertAllowedPath(root, this.config.allowedRoots);
     }
     async loadInitialAgentsFiles(root) {
-        const agentDir = resolve(this.config.agentDir);
         const resolvedRoot = (await tryRealpath(root)) ?? root;
-        const resolvedAgentDir = (await tryRealpath(agentDir)) ?? agentDir;
+        const systemInstructionsPath = resolve(this.config.systemInstructionsPath);
         const loadedFiles = [];
-        for (const file of loadProjectContextFiles({ cwd: root, agentDir })) {
-            const path = resolve(file.path);
-            if (!isInitialAgentsFilePath(path, root, agentDir))
-                continue;
-            const content = await readResolvedContextFile(path, file.content, resolvedRoot, resolvedAgentDir);
+        const loadedRealPaths = new Set();
+        const systemInstructions = await readSystemInstructions(systemInstructionsPath);
+        const systemInstructionsRealPath = await tryRealpath(systemInstructionsPath);
+        if (systemInstructions !== undefined) {
+            loadedFiles.push({
+                path: systemInstructionsPath,
+                content: systemInstructions,
+            });
+            if (systemInstructionsRealPath)
+                loadedRealPaths.add(systemInstructionsRealPath);
+        }
+        for (const fileName of CONTEXT_FILE_NAMES) {
+            const path = join(root, fileName);
+            const content = await readResolvedProjectContextFile(path, resolvedRoot);
             if (content === undefined)
                 continue;
+            const realPath = await tryRealpath(path);
+            if (realPath && loadedRealPaths.has(realPath))
+                continue;
             loadedFiles.push({
                 path,
                 content,
             });
+            if (realPath)
+                loadedRealPaths.add(realPath);
         }
         return loadedFiles;
     }
@@ -408,7 +420,10 @@ export class WorkspaceRegistry {
                 loadedRealPaths.add(realPath);
         }
         const discovered = [];
+        const agentDir = resolve(this.config.agentDir);
         await walkWorkspace(root, async (path, entry) => {
+            if (isPathInsideRoot(path, agentDir))
+                return;
             if (!entry.isFile())
                 return;
             if (!CONTEXT_FILE_NAMES.has(entry.name))
@@ -480,20 +495,32 @@ export function formatAgentsPath(path, workspaceRoot) {
     }
     return relationship.split(sep).join("/");
 }
-function isInitialAgentsFilePath(path, root, agentDir) {
-    if (isPathInsideRoot(path, agentDir))
-        return true;
+function isProjectRootInstructionPath(path, root) {
     return isPathInsideRoot(path, root) && dirname(path) === root;
 }
-async function readResolvedContextFile(path, fallbackContent, root, agentDir) {
+async function readSystemInstructions(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function readResolvedProjectContextFile(path, root) {
     try {
         const resolvedPath = await realpath(path);
-        if (!isInitialAgentsFilePath(resolvedPath, root, agentDir))
+        if (!isProjectRootInstructionPath(resolvedPath, root))
             return undefined;
         return await readFile(resolvedPath, "utf8");
     }
-    catch {
-        return fallbackContent;
+    catch (error) {
+        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            return undefined;
+        }
+        throw error;
     }
 }
 async function tryRealpath(path) {

package/docs/chatgpt-coding-workflow.md

@@ -87,10 +87,14 @@ placed into a merge-conflict state.
 Legacy `devspace/*` managed branches remain closable when they are already stored
 in workspace metadata; only new managed branches use `forgerelay/*`.
 
-## Project instructions
+## Instructions
 
-When a workspace opens, ForgeRelay loads root-level instruction files when they
-exist:
+When a workspace opens, ForgeRelay first loads exactly one global system-instructions
+file. The default is `~/.agents/AGENTS.md`; configure a different single path with
+`FORGERELAY_SYSTEM_INSTRUCTIONS_PATH`. Symbolic links are followed so this entry can
+point at a canonical source elsewhere on disk.
+
+ForgeRelay then loads root-level project instruction files when they exist:
 
 ```text
 AGENTS.md
@@ -99,8 +103,10 @@ CLAUDE.md
 CLAUDE.MD
 ```
 
-Nested instruction files are returned as available paths rather than all being
-injected eagerly. Read the relevant nested file before working under that path.
+Nested project instruction files are returned as available paths rather than all
+being injected eagerly. Read the relevant nested file before working under that path.
+`FORGERELAY_AGENT_DIR` is not an instruction source; it remains only a compatibility
+skill-discovery path.
 
 ## Agent Skills
 

package/docs/configuration.md

@@ -136,6 +136,18 @@ programs when the optional `node-pty` dependency is available.
 | `changes` | Attach UI to `open_workspace` and aggregate `show_changes`. |
 | `off` | Disable widget UI. |
 
+## System instructions
+
+ForgeRelay loads exactly one global system-instructions file. The default is
+`~/.agents/AGENTS.md`. Set `FORGERELAY_SYSTEM_INSTRUCTIONS_PATH` or the
+`systemInstructionsPath` config key to point at a different single file.
+Arrays or empty values are not accepted. Symbolic links are followed, so the
+runtime entry may point at a canonical source elsewhere on disk.
+
+Project-root `AGENTS.md` / `CLAUDE.md` files remain project context and are
+loaded separately. `FORGERELAY_AGENT_DIR` does not select a global instruction
+file; it remains a compatibility path for Agent Skills.
+
 ## Skills and subagents
 
 | Variable | Purpose |

package/docs/versioning.md

@@ -94,24 +94,30 @@ npm run release:tag-check -- v0.1.0
 A release tag must exactly equal `v` followed by the package version, and
 `Unreleased` must be empty.
 
-## Tag-triggered publishing
+## CI and tag-triggered publishing
 
-`.github/workflows/release.yml` runs for tags matching `v*.*.*` in the
-`Akira-TL/forgerelay` repository. The release helper performs the strict SemVer
-validation; tags that only match the broad GitHub glob but not the package
-version are rejected.
+`.github/workflows/ci.yml` is a reusable workflow with only a `workflow_call`
+entry point. It does not run on ordinary branch pushes, pull-request updates, or
+manual dispatches. Day-to-day development therefore does not consume cloud CI.
+
+`.github/workflows/release.yml` is the single GitHub Actions entry point. It runs
+only for stable SemVer tags matching `v[0-9]+.[0-9]+.[0-9]+` in the
+`Akira-TL/forgerelay` repository. The release helper then requires the tag to
+exactly equal `v` plus the package version. Ordinary branch pushes never enter
+cloud CI or publication.
 
 For a valid tag, the workflow:
 
-1. checks out the tagged commit with full Git history;
-2. verifies the tagged commit is contained in `origin/main`;
-3. installs dependencies;
-4. checks the tag against `package.json` and `CHANGELOG.md`;
-5. runs `npm run release:verify`;
-6. runs `npm pack --dry-run`;
-7. checks whether the exact npm version is already published;
-8. publishes `@akira-tl/forgerelay` when necessary;
-9. creates the matching GitHub Release after npm publication succeeds.
+1. invokes `.github/workflows/ci.yml` for the cloud multi-platform verification;
+2. waits for every CI matrix job to pass;
+3. checks out the tagged commit with full Git history;
+4. verifies the tagged commit is contained in `origin/main`;
+5. installs dependencies and checks the tag against `package.json` and `CHANGELOG.md`;
+6. rebuilds the publish artifact on the publication runner;
+7. runs `npm pack --dry-run`;
+8. checks whether the exact npm version is already published;
+9. publishes `@akira-tl/forgerelay` when necessary;
+10. creates the matching GitHub Release after npm publication succeeds.
 
 The npm existence check makes the workflow safely restartable when npm
 publication succeeds but GitHub Release creation fails afterward.
@@ -152,7 +158,8 @@ npm publishing token.
 3. Run the appropriate `release:patch`, `release:minor`, or `release:major`
    command.
 4. Review the generated version and changelog diff.
-5. Run `npm run release:verify`.
+5. Run `npm run release:verify` locally. This full local gate is a release-time
+   operation; ordinary development pushes do not need to run the full release gate.
 6. Commit the release-ready code and metadata and push `main`.
 7. Create the exact version tag, for example:
 

package/package.json

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