@akira-tl/forgerelay 1.2.4 → 1.3.0

package/dist/runtime/config/config.js

@@ -2,11 +2,12 @@ import { isIP } from "node:net";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandHomePath } from "../../mcp/filesystem/roots.js";
-import { forgerelaySkillsDir, generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
+import { normalizeAllowedRootPaths } from "./validation/paths.js";
+import { generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
 import { DEFAULT_MEDIA_MAX_BYTES } from "../../mcp/operations/media-content.js";
 import { shellInstructionPath } from "../instructions/shell-instructions.js";
 import { resolveConfiguredCommandShellRuntime, } from "../shell/command-shell-runtime.js";
-import { generalConfigDefinition } from "./definition/general-config.js";
+import { DEFAULT_INSTRUCTION_NAMES, DEFAULT_SKILL_PATHS, generalConfigDefinition, } from "./definition/general-config.js";
 import { resolveGeneralConfig } from "./resolution/general.js";
 import { assertConfigResolutionValid } from "./resolution/resolver.js";
 import { ConfigRuntime } from "./runtime/config-runtime.js";
@@ -15,16 +16,8 @@ const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 const DEFAULT_ARTIFACT_MAX_FILE_BYTES = 100 * 1024 * 1024;
 const DEFAULT_TASK_REMINDER_INTERVAL = 30;
 function parseAllowedRoots(value) {
-    if (Array.isArray(value)) {
-        const roots = value.map((entry) => entry.trim()).filter(Boolean);
-        return (roots.length > 0 ? roots : [process.cwd()]).map((root) => resolve(expandHomePath(root)));
-    }
-    const rawRoots = value
-        ?.split(",")
-        .map((entry) => entry.trim())
-        .filter(Boolean) ?? [];
-    const roots = rawRoots.length > 0 ? rawRoots : [process.cwd()];
-    return roots.map((root) => resolve(expandHomePath(root)));
+    const roots = Array.isArray(value) ? value : value?.split(",") ?? [];
+    return normalizeAllowedRootPaths(roots);
 }
 function parseAllowedHosts(value, derivedHosts) {
     if (Array.isArray(value)) {
@@ -85,12 +78,6 @@ function parseLogFormat(value) {
         return "json";
     throw new Error(`Invalid FORGERELAY_LOG_FORMAT: ${value}`);
 }
-function parsePathList(value) {
-    return (value
-        ?.split(",")
-        .map((entry) => entry.trim())
-        .filter(Boolean) ?? []);
-}
 function parseStringList(value, fallback) {
     const entries = value
         ?.split(",")
@@ -244,13 +231,7 @@ function resolvePublicDeployment(configuredValue, host, port) {
         canonicalBaseUrl: baseUrls[0],
     };
 }
-export function loadConfig(env = process.env, options = {}) {
-    const configRuntime = new ConfigRuntime();
-    const runtimeEnvironment = generalConfigRuntimeEnvironment(env);
-    configRuntime.captureResolutionInputs(generalConfigDefinition.domain, {
-        environment: runtimeEnvironment,
-        ...(options.runtimeOverrides ? { cli: options.runtimeOverrides } : {}),
-    });
+function resolveGeneralRuntimeConfig(env, options = {}) {
     const files = loadForgeRelayFiles(env);
     const generalResolution = resolveGeneralConfig({
         env,
@@ -265,11 +246,31 @@ export function loadConfig(env = process.env, options = {}) {
     });
     assertConfigResolutionValid(generalResolution);
     const config = generalResolution.values;
-    refreshGeneralUserConfigSource(configRuntime, files.configPath, runtimeEnvironment);
-    const instanceId = files.auth.instanceId?.trim() || generateInstanceId();
     const host = config.host ?? "127.0.0.1";
     const port = config.port ?? 7676;
     const publicDeployment = resolvePublicDeployment(config.publicBaseUrl, host, port);
+    return { files, config, host, port, publicDeployment };
+}
+export function resolveRuntimeConfigFacts(env = process.env) {
+    const { files, config, host, port, publicDeployment } = resolveGeneralRuntimeConfig(env);
+    return {
+        ...(files.auth.instanceId?.trim() ? { instanceId: files.auth.instanceId.trim() } : {}),
+        stateDir: resolve(expandHomePath(config.stateDir ?? defaultStateDir())),
+        host,
+        port,
+        publicBaseUrl: publicDeployment.canonicalBaseUrl,
+    };
+}
+export function loadConfig(env = process.env, options = {}) {
+    const configRuntime = new ConfigRuntime();
+    const runtimeEnvironment = generalConfigRuntimeEnvironment(env);
+    configRuntime.captureResolutionInputs(generalConfigDefinition.domain, {
+        environment: runtimeEnvironment,
+        ...(options.runtimeOverrides ? { cli: options.runtimeOverrides } : {}),
+    });
+    const { files, config, host, port, publicDeployment } = resolveGeneralRuntimeConfig(env, options);
+    refreshGeneralUserConfigSource(configRuntime, files.configPath, runtimeEnvironment);
+    const instanceId = files.auth.instanceId?.trim() || generateInstanceId();
     const publicBaseUrl = publicDeployment.canonicalBaseUrl;
     const proxyTrust = resolveProxyTrust(env, config, host, publicBaseUrl);
     const commandShellRuntime = resolveConfiguredCommandShellRuntime(config.commandShell, process.platform, env);
@@ -305,8 +306,8 @@ export function loadConfig(env = process.env, options = {}) {
         mediaMaxBytes: config.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES,
         taskReminderInterval: config.taskReminderInterval ?? DEFAULT_TASK_REMINDER_INTERVAL,
         skillsEnabled: productEnv(env, "SKILLS") === undefined ? true : parseBoolean(productEnv(env, "SKILLS")),
-        skillPaths: parsePathList(productEnv(env, "SKILL_PATHS")),
-        configSkillsDir: forgerelaySkillsDir(env),
+        skillPaths: config.skillPaths ?? [...DEFAULT_SKILL_PATHS],
+        instructionNames: config.instructionNames ?? [...DEFAULT_INSTRUCTION_NAMES],
         subagents: config.subagents === true,
         allowAgentLanguageServerInstall: config.allowAgentLanguageServerInstall === true,
         agentDir: resolve(expandHomePath(config.agentDir ?? defaultAgentDir())),

package/dist/runtime/config/definition/general-config.js

@@ -1,7 +1,12 @@
 import * as z from "zod/v4";
 import { defineConfigDomain } from "./definition.js";
+import { LISTEN_PORT_MIN, PORT_MAX } from "../validation/ports.js";
 const USER_RUNTIME_SCOPES = ["runtime", "user", "built-in"];
+const CONTEXT_SOURCE_SCOPES = ["runtime", "project-local", "project", "user", "built-in"];
 const USER_SCOPES = ["user", "built-in"];
+export const DEFAULT_SYSTEM_INSTRUCTIONS_PATH = "~/.agents/AGENTS.md";
+export const DEFAULT_INSTRUCTION_NAMES = ["AGENTS.md"];
+export const DEFAULT_SKILL_PATHS = ["~/.agents/skills", "./.agents/skills"];
 const USER_ONLY_SCOPES = ["user"];
 const LEGACY_REMOVAL_VERSION = "1.4.0";
 const commandShellSchema = z.object({
@@ -13,6 +18,7 @@ const retentionSchema = z.object({
     historyDays: z.number().int().min(1).max(36_500).optional(),
     orphanedAdministrativeState: z.boolean().optional(),
 }).strict();
+const instructionNameSchema = z.string().trim().min(1).refine((value) => value !== "." && value !== ".." && !value.includes("/") && !value.includes("\\"), "Instruction name must be one basename without path separators.");
 export const generalConfigDefinition = defineConfigDomain({
     domain: "config",
     title: "ForgeRelay general configuration",
@@ -24,11 +30,11 @@ export const generalConfigDefinition = defineConfigDomain({
             reload: "restart-required",
             runtimeOverride: runtimeEnv("HOST", (env) => env.HOST),
         }),
-        port: field(z.number().int().min(1).max(65535), "Local listening port.", {
+        port: field(z.number().int().min(LISTEN_PORT_MIN).max(PORT_MAX), `Local listening port (${LISTEN_PORT_MIN}-${PORT_MAX}).`, {
             scopes: USER_RUNTIME_SCOPES,
             builtIn: literal(7676),
             reload: "restart-required",
-            runtimeOverride: runtimeEnv("PORT", (env) => readIntegerEnv(env, "PORT", 1, 65535)),
+            runtimeOverride: runtimeEnv("PORT", (env) => readIntegerEnv(env, "PORT", LISTEN_PORT_MIN, PORT_MAX)),
         }),
         allowedRoots: field(z.array(z.string()), "Filesystem roots that Workspaces may open.", {
             scopes: USER_RUNTIME_SCOPES,
@@ -112,14 +118,24 @@ export const generalConfigDefinition = defineConfigDomain({
             reload: "restart-required",
             runtimeOverride: runtimeEnv("FORGERELAY_AGENT_DIR", (env) => env.FORGERELAY_AGENT_DIR),
         }),
-        systemInstructionsPath: field(z.string().min(1), "Global Agent instruction file consumed by ForgeRelay.", {
-            scopes: USER_RUNTIME_SCOPES,
-            builtIn: computed("~/.agents/AGENTS.md"),
+        systemInstructionsPath: field(z.string().trim().min(1), "Selected system-level Agent instruction file consumed by ForgeRelay.", {
+            scopes: CONTEXT_SOURCE_SCOPES,
+            builtIn: literal(DEFAULT_SYSTEM_INSTRUCTIONS_PATH),
             runtimeOverride: runtimeEnv("FORGERELAY_SYSTEM_INSTRUCTIONS_PATH", (env) => readNonEmptyPathEnv(env, "FORGERELAY_SYSTEM_INSTRUCTIONS_PATH")),
         }),
+        instructionNames: field(z.array(instructionNameSchema), "Project instruction basenames discovered hierarchically within a Workspace.", {
+            scopes: CONTEXT_SOURCE_SCOPES,
+            builtIn: literal([...DEFAULT_INSTRUCTION_NAMES]),
+            runtimeOverride: runtimeEnv("FORGERELAY_INSTRUCTION_NAMES", (env) => readListEnv(env, "FORGERELAY_INSTRUCTION_NAMES")),
+        }),
+        skillPaths: field(z.array(z.string().trim().min(1)), "Ordered Agent Skill source directories; explicit higher-precedence lists replace lower-precedence lists.", {
+            scopes: CONTEXT_SOURCE_SCOPES,
+            builtIn: literal([...DEFAULT_SKILL_PATHS]),
+            runtimeOverride: runtimeEnv("FORGERELAY_SKILL_PATHS", (env) => readListEnv(env, "FORGERELAY_SKILL_PATHS")),
+        }),
         commandShell: field(commandShellSchema, "Recorded command-shell preference for ForgeRelay command and Hook execution.", {
             scopes: USER_SCOPES,
-            builtIn: computed("Detected launcher shell with the recorded compatibility fallback used when needed."),
+            builtIn: computed("Platform compatibility default unless an explicit shell preference is recorded."),
             reload: "restart-required",
         }),
         shellInstructions: field(z.boolean(), "Enable ForgeRelay-owned runtime shell instructions.", {

package/dist/runtime/config/external-mcp-config.js

@@ -1,4 +1,5 @@
 import * as z from "zod/v4";
+import { isIntegerPort, OAUTH_CALLBACK_PORT_MIN, PORT_MAX } from "./validation/ports.js";
 const MCP_SERVER_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
 const MAX_MCP_SERVERS = 32;
 const nonEmptyStringSchema = z.string().trim().min(1);
@@ -13,7 +14,7 @@ const clientMetadataUrlSchema = z.string().url().refine((value) => {
 }, "clientMetadataUrl must use https and contain a non-root path.");
 const oauthSourceSchema = z.object({
     clientMetadataUrl: clientMetadataUrlSchema,
-    callbackPort: z.number().int().min(1024).max(65535),
+    callbackPort: z.number().int().min(OAUTH_CALLBACK_PORT_MIN).max(PORT_MAX),
 }).strict();
 const stdioSourceSchema = z.object({
     transport: z.literal("stdio"),
@@ -136,8 +137,8 @@ function parseOAuthClientConfig(value, label) {
         throw new Error(`${label}.clientMetadataUrl must use https and contain a non-root path.`);
     }
     const callbackPort = value.callbackPort;
-    if (!Number.isInteger(callbackPort) || Number(callbackPort) < 1024 || Number(callbackPort) > 65535) {
-        throw new Error(`${label}.callbackPort must be an integer from 1024 to 65535.`);
+    if (!isIntegerPort(callbackPort, OAUTH_CALLBACK_PORT_MIN, PORT_MAX)) {
+        throw new Error(`${label}.callbackPort must be an integer from ${OAUTH_CALLBACK_PORT_MIN} to ${PORT_MAX}.`);
     }
     return {
         clientMetadataUrl: parsed.toString(),

package/dist/runtime/config/resolution/resolver.js

@@ -367,8 +367,7 @@ function appendFieldDeprecations(diagnostics, field, candidates, logicalPath) {
             code: "deprecated_source",
             source: candidate.source,
             logicalPath,
-            message: `${logicalPath} is deprecated since ForgeRelay ${field.deprecation.since}` +
-                (field.deprecation.replacement ? `; use ${field.deprecation.replacement}.` : "."),
+            message: deprecationMessage(logicalPath, field.deprecation),
         });
     }
 }
@@ -394,10 +393,14 @@ function sourceDeprecationDiagnostic(source, deprecation) {
         severity: "warning",
         code: "deprecated_source",
         source,
-        message: `Configuration source ${source.location ?? source.id} is deprecated since ForgeRelay ${deprecation.since}` +
-            (deprecation.replacement ? `; use ${deprecation.replacement}.` : "."),
+        message: deprecationMessage(`Configuration source ${source.location ?? source.id}`, deprecation),
     };
 }
+function deprecationMessage(subject, deprecation) {
+    return `${subject} is deprecated since ForgeRelay ${deprecation.since}` +
+        (deprecation.removeIn ? ` and will be removed in ForgeRelay ${deprecation.removeIn}` : "") +
+        (deprecation.replacement ? `; use ${deprecation.replacement}.` : ".");
+}
 function diagnosticForSourceError(source, error) {
     const missingEnvironment = missingEnvironmentName(error);
     if (missingEnvironment) {

package/dist/runtime/config/user-config.js

@@ -5,6 +5,8 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { withFileLock } from "../state/lock/file-lock.js";
 import { expandHomePath } from "../../mcp/filesystem/roots.js";
+import { parseConfigSource } from "./definition/definition.js";
+import { generalConfigDefinition } from "./definition/general-config.js";
 export function forgerelayConfigDir(env = process.env) {
     const explicit = env.FORGERELAY_CONFIG_DIR;
     if (explicit)
@@ -23,9 +25,6 @@ export function forgerelayHooksPath(env = process.env) {
 export function forgerelayHooksDir(env = process.env) {
     return join(forgerelayConfigDir(env), "hooks");
 }
-export function forgerelaySkillsDir(env = process.env) {
-    return join(forgerelayConfigDir(env), "skills");
-}
 export function loadForgeRelayFiles(env = process.env, options = {}) {
     const dir = forgerelayConfigDir(env);
     const configPath = join(dir, "config.json");
@@ -49,8 +48,9 @@ export function loadForgeRelayFiles(env = process.env, options = {}) {
 }
 export function writeForgeRelayConfig(config, env = process.env) {
     const filePath = forgerelayConfigPath(env);
+    const validated = parseConfigSource(generalConfigDefinition, "user", config);
     mkdirSync(forgerelayConfigDir(env), { recursive: true });
-    writeJsonFile(filePath, config, 0o600);
+    writeConfigJsonFile(filePath, validated, 0o600);
     return filePath;
 }
 export async function writeForgeRelayAuth(auth, env = process.env) {
@@ -185,10 +185,13 @@ async function replaceAuthFile(tempPath, filePath) {
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function writeJsonFile(filePath, value, mode) {
+export function writeConfigJsonFile(filePath, value, mode) {
+    writeConfigTextFile(filePath, JSON.stringify(value, null, 2) + "\n", mode);
+}
+export function writeConfigTextFile(filePath, value, mode) {
     const tempPath = `${filePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
     try {
-        writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n", { mode });
+        writeFileSync(tempPath, value, { mode });
         renameSync(tempPath, filePath);
     }
     finally {

package/dist/runtime/config/validation/paths.js

@@ -0,0 +1,12 @@
+import { resolve } from "node:path";
+import { expandHomePath } from "../../../mcp/filesystem/roots.js";
+export function normalizeAllowedRootPath(value) {
+    const root = value.trim();
+    if (!root)
+        throw new Error("Allowed root must be a non-empty path.");
+    return resolve(expandHomePath(root));
+}
+export function normalizeAllowedRootPaths(values, fallback = [process.cwd()]) {
+    const roots = values.map((entry) => entry.trim()).filter(Boolean);
+    return (roots.length > 0 ? roots : fallback).map(normalizeAllowedRootPath);
+}

package/dist/runtime/config/validation/ports.js

@@ -0,0 +1,9 @@
+export const LISTEN_PORT_MIN = 1;
+export const PORT_MAX = 65_535;
+export const OAUTH_CALLBACK_PORT_MIN = 1_024;
+export function isIntegerPort(value, minimum = LISTEN_PORT_MIN, maximum = PORT_MAX) {
+    return typeof value === "number"
+        && Number.isInteger(value)
+        && value >= minimum
+        && value <= maximum;
+}

package/dist/subagents/profiles.js

@@ -307,6 +307,43 @@ function legacyProfileFromDocument(content, filePath) {
     const parsed = parseFrontmatter(content, filePath);
     return legacyProfileFromFrontmatter(parsed.frontmatter, parsed.body, filePath);
 }
+export function canonicalSubagentProfileValueFromDocument(content, filePath) {
+    const profile = canonicalProfileFromDocument(content, filePath);
+    if (profile.disabled)
+        return { disabled: true };
+    return {
+        description: profile.description,
+        provider: profile.provider,
+        ...(profile.model ? { model: profile.model } : {}),
+        ...(profile.thinking ? { thinking: profile.thinking } : {}),
+        body: profile.body,
+    };
+}
+export function canonicalSubagentProfileDocument(name, value) {
+    const normalizedName = profileNameSchema.parse(name);
+    const disabled = subagentProfileDisabledSchema.safeParse(value);
+    if (disabled.success) {
+        return [
+            FRONTMATTER_DELIMITER,
+            `name: ${JSON.stringify(normalizedName)}`,
+            "disabled: true",
+            FRONTMATTER_DELIMITER,
+            "",
+        ].join("\n");
+    }
+    const profile = subagentProfileValueSchema.parse(value);
+    return [
+        FRONTMATTER_DELIMITER,
+        `name: ${JSON.stringify(normalizedName)}`,
+        `description: ${JSON.stringify(profile.description)}`,
+        `provider: ${profile.provider}`,
+        ...(profile.model ? [`model: ${JSON.stringify(profile.model)}`] : []),
+        ...(profile.thinking ? [`thinking: ${JSON.stringify(profile.thinking)}`] : []),
+        FRONTMATTER_DELIMITER,
+        profile.body,
+        "",
+    ].join("\n");
+}
 export function canonicalSubagentProfileDocumentFromLegacy(content, filePath) {
     const profile = legacyProfileFromDocument(content, filePath);
     const frontmatter = [

package/dist/workspaces/bootstrap.js

@@ -22,21 +22,38 @@ export function resolveBootstrapContextComponents(mode, currentFingerprints, del
     return BOOTSTRAP_CONTEXT_COMPONENTS.filter((component) => !deliveries.some((delivery) => delivery.componentFingerprints?.[component] === currentFingerprints[component]));
 }
 export function bootstrapContextFingerprints(workspace, agentsFiles, availableAgentsFiles) {
+    const instructionSources = {
+        systemInstructionsPath: resolve(workspace.contextSources.systemInstructionsPath),
+        instructionNames: [...workspace.contextSources.instructionNames],
+    };
+    const skillSources = { skillPaths: [...workspace.contextSources.skillPaths] };
     const payload = {
-        agentsFiles: agentsFiles
-            .map((file) => ({ path: resolve(file.path), content: file.content }))
-            .sort((left, right) => left.path.localeCompare(right.path)),
-        availableAgentsFiles: availableAgentsFiles
-            .map((file) => resolve(file.path))
-            .sort((left, right) => left.localeCompare(right)),
-        skills: workspace.skills
-            .map((skill) => ({
-            name: skill.name,
-            description: skill.description,
-            filePath: resolve(skill.filePath),
-        }))
-            .sort((left, right) => left.name.localeCompare(right.name) || left.filePath.localeCompare(right.filePath)),
-        skillDiagnostics: workspace.skillDiagnostics,
+        agentsFiles: {
+            sources: instructionSources,
+            files: agentsFiles
+                .map((file) => ({ path: resolve(file.path), content: file.content }))
+                .sort((left, right) => left.path.localeCompare(right.path)),
+        },
+        availableAgentsFiles: {
+            sources: instructionSources,
+            files: availableAgentsFiles
+                .map((file) => resolve(file.path))
+                .sort((left, right) => left.localeCompare(right)),
+        },
+        skills: {
+            sources: skillSources,
+            resources: workspace.skills
+                .map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+                filePath: resolve(skill.filePath),
+            }))
+                .sort((left, right) => left.name.localeCompare(right.name) || left.filePath.localeCompare(right.filePath)),
+        },
+        skillDiagnostics: {
+            sources: skillSources,
+            diagnostics: workspace.skillDiagnostics,
+        },
         capabilityGuides: workspace.capabilityGuides
             .map((guide) => ({
             name: guide.name,

package/dist/workspaces/context.js

@@ -4,10 +4,10 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { markCapabilityGuideActivated, resolveCapabilityGuideReadPath, } from "../mcp/server/core/capabilities.js";
 import { readShellInstruction } from "../runtime/instructions/shell-instructions.js";
 import { assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "../mcp/filesystem/roots.js";
-import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./resources/skills.js";
+import { loadWorkspaceSkills, markSkillActivated, redactSkillDiagnosticMessage, resolveSkillReadPath, } from "./resources/skills.js";
+import { defaultWorkspaceContextSources, resolveWorkspaceContextSources, } from "./resources/context-sources.js";
 import { WorkspaceResourceMonitor, } from "./resources/resource-monitor.js";
 const INITIAL_INSTRUCTION_DISCOVERY_DEPTH = 1;
-const CONTEXT_FILE_NAMES = new Set(["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
 const SKIPPED_CONTEXT_DIRS = new Set([
     ".git",
     ".hg",
@@ -28,6 +28,7 @@ const SKIPPED_CONTEXT_DIRS = new Set([
 export class WorkspaceContextService {
     config;
     resourceMonitor = new WorkspaceResourceMonitor();
+    contextSourceRefreshes = new Map();
     constructor(config) {
         this.config = config;
     }
@@ -114,7 +115,7 @@ export class WorkspaceContextService {
         // system/shell instructions are intentionally exempt because they are
         // trusted inputs explicitly advertised by ForgeRelay.
         const trustedExternalInstructionPaths = new Set([
-            resolve(this.config.systemInstructionsPath),
+            resolve(workspace.contextSources.systemInstructionsPath),
             ...(this.config.shellInstructionPath ? [resolve(this.config.shellInstructionPath)] : []),
         ]);
         if (!trustedExternalInstructionPaths.has(resolve(selectedPath))) {
@@ -136,8 +137,72 @@ export class WorkspaceContextService {
         const directory = workingDirectory ? this.resolvePath(workspace, workingDirectory) : workspace.root;
         return assertAllowedPath(directory, [workspace.root]);
     }
-    loadSkillsForWorkspace(root) {
-        const result = loadWorkspaceSkills(this.config, root);
+    defaultContextSources(root) {
+        return defaultWorkspaceContextSources(this.config, root);
+    }
+    async loadContextSourcesForWorkspace(project, root) {
+        const contextSources = await resolveWorkspaceContextSources(this.config, project, root);
+        return {
+            contextSources,
+            ...this.loadSkillsForWorkspace(root, contextSources.skillPaths),
+        };
+    }
+    async refreshContextSourcesForWorkspace(workspace) {
+        const existing = this.contextSourceRefreshes.get(workspace.id);
+        if (existing)
+            return existing;
+        const refresh = this.applyContextSourceRefresh(workspace);
+        this.contextSourceRefreshes.set(workspace.id, refresh);
+        try {
+            await refresh;
+        }
+        finally {
+            if (this.contextSourceRefreshes.get(workspace.id) === refresh)
+                this.contextSourceRefreshes.delete(workspace.id);
+        }
+    }
+    async applyContextSourceRefresh(workspace) {
+        if (!workspace.project)
+            return;
+        const contextSources = await resolveWorkspaceContextSources(this.config, workspace.project, workspace.root);
+        if (sameContextSources(workspace.contextSources, contextSources))
+            return;
+        const previousSources = workspace.contextSources;
+        const previousLoadedPaths = new Set([...workspace.loadedInstructionPaths].map((path) => resolve(path)));
+        const previousKnownPaths = new Set([...workspace.knownInstructionPathsByDir.values()].flat().map((path) => resolve(path)));
+        const previousAvailablePaths = new Set([...previousKnownPaths].filter((path) => !previousLoadedPaths.has(path)));
+        const previousSkills = workspace.skills.map((skill) => ({ ...skill }));
+        const previousSkillDiagnostics = workspace.skillDiagnostics.map((diagnostic) => ({ ...diagnostic }));
+        const nextSkills = this.loadSkillsForWorkspace(workspace.root, contextSources.skillPaths);
+        workspace.contextSources = contextSources;
+        workspace.skills = nextSkills.skills;
+        workspace.skillDiagnostics = nextSkills.skillDiagnostics;
+        const retainedSkillDirs = new Set(workspace.skills.map((skill) => resolve(skill.baseDir)));
+        for (const activatedDir of [...workspace.activatedSkillDirs]) {
+            if (!retainedSkillDirs.has(resolve(activatedDir)))
+                workspace.activatedSkillDirs.delete(activatedDir);
+        }
+        workspace.scannedInstructionDirs.clear();
+        workspace.knownInstructionPathsByDir.clear();
+        workspace.loadedInstructionRealPaths.clear();
+        workspace.loadedInstructionPaths.clear();
+        workspace.workspaceInstructions.length = 0;
+        const agentsFiles = await this.loadInitialAgentsFiles(workspace);
+        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace, agentsFiles);
+        this.trackWorkspaceResources(workspace, agentsFiles, availableAgentsFiles);
+        this.resourceMonitor.announce(workspace.id, formatContextSourceRefresh({
+            workspace,
+            previousSources,
+            previousLoadedPaths,
+            previousAvailablePaths,
+            previousSkills,
+            previousSkillDiagnostics,
+            agentsFiles,
+            availableAgentsFiles,
+        }), ["agentsFiles", "availableAgentsFiles", "skills", "skillDiagnostics"]);
+    }
+    loadSkillsForWorkspace(root, skillPaths = this.config.skillPaths) {
+        const result = loadWorkspaceSkills(this.config, root, skillPaths);
         return {
             skills: result.skills,
             skillDiagnostics: result.diagnostics,
@@ -154,7 +219,7 @@ export class WorkspaceContextService {
         return assertAllowedPath(root, this.config.allowedRoots);
     }
     async loadInitialAgentsFiles(workspace) {
-        const systemInstructionsPath = resolve(this.config.systemInstructionsPath);
+        const systemInstructionsPath = resolve(workspace.contextSources.systemInstructionsPath);
         const loadedFiles = [];
         const systemInstructions = await readSystemInstructions(systemInstructionsPath);
         const systemInstructionsRealPath = await tryRealpath(systemInstructionsPath);
@@ -164,6 +229,9 @@ export class WorkspaceContextService {
             if (systemInstructionsRealPath)
                 workspace.loadedInstructionRealPaths.add(systemInstructionsRealPath);
         }
+        else {
+            workspace.workspaceInstructions.push({ path: systemInstructionsPath, status: "unavailable" });
+        }
         const shellInstructionPath = this.config.shellInstructionPath;
         if (shellInstructionPath) {
             const shellInstruction = await readShellInstruction(shellInstructionPath);
@@ -282,7 +350,7 @@ export class WorkspaceContextService {
         const childDirectories = [];
         for await (const entry of entries) {
             const path = join(resolvedDirectory, entry.name);
-            if (entry.isFile() && CONTEXT_FILE_NAMES.has(entry.name)) {
+            if (entry.isFile() && workspace.contextSources.instructionNames.includes(entry.name)) {
                 instructionPaths.push(path);
                 continue;
             }
@@ -341,6 +409,90 @@ export function formatAgentsPath(path, workspaceRoot) {
     }
     return relationship.split(sep).join("/");
 }
+function sameContextSources(left, right) {
+    return left.systemInstructionsPath === right.systemInstructionsPath &&
+        sameStringList(left.instructionNames, right.instructionNames) &&
+        sameStringList(left.skillPaths, right.skillPaths);
+}
+function sameStringList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function formatContextSourceRefresh(input) {
+    const { workspace, previousSources, previousLoadedPaths, previousAvailablePaths, previousSkills, previousSkillDiagnostics, agentsFiles, availableAgentsFiles, } = input;
+    const sections = ["Agent context source configuration changed; the effective Workspace context has been refreshed without reopening the Workspace."];
+    if (previousSources.systemInstructionsPath !== workspace.contextSources.systemInstructionsPath) {
+        sections.push([
+            "System instruction source changed:",
+            `- ${formatAgentsPath(previousSources.systemInstructionsPath, workspace.root)}`,
+            `+ ${formatAgentsPath(workspace.contextSources.systemInstructionsPath, workspace.root)}`,
+        ].join("\n"));
+    }
+    if (!sameStringList(previousSources.instructionNames, workspace.contextSources.instructionNames)) {
+        sections.push([
+            "Project instruction filename selection changed:",
+            `- ${previousSources.instructionNames.join(", ") || "(none)"}`,
+            `+ ${workspace.contextSources.instructionNames.join(", ") || "(none)"}`,
+        ].join("\n"));
+    }
+    if (!sameStringList(previousSources.skillPaths, workspace.contextSources.skillPaths)) {
+        sections.push([
+            "Skill source path selection changed:",
+            `- ${previousSources.skillPaths.join(", ") || "(none)"}`,
+            `+ ${workspace.contextSources.skillPaths.join(", ") || "(none)"}`,
+        ].join("\n"));
+    }
+    const currentLoadedPaths = new Set(agentsFiles.map((file) => resolve(file.path)));
+    for (const path of [...previousLoadedPaths].filter((path) => !currentLoadedPaths.has(path)).sort()) {
+        sections.push(`Instruction source is no longer active: ${formatAgentsPath(path, workspace.root)}`);
+    }
+    for (const file of agentsFiles) {
+        if (previousLoadedPaths.has(resolve(file.path)))
+            continue;
+        sections.push([
+            `Instruction source loaded: ${formatAgentsPath(file.path, workspace.root)}`,
+            file.content,
+        ].join("\n"));
+    }
+    const currentAvailablePaths = new Set(availableAgentsFiles.map((file) => resolve(file.path)));
+    for (const path of [...previousAvailablePaths].filter((path) => !currentAvailablePaths.has(path)).sort()) {
+        sections.push(`Lazy Workspace instruction is no longer advertised: ${formatAgentsPath(path, workspace.root)}`);
+    }
+    for (const file of availableAgentsFiles) {
+        if (previousAvailablePaths.has(resolve(file.path)))
+            continue;
+        sections.push(`Lazy Workspace instruction is now available: ${formatAgentsPath(file.path, workspace.root)}. Read it before working under that directory.`);
+    }
+    const previousSkillKeys = new Map(previousSkills.map((skill) => [
+        `${skill.name}\u0000${resolve(skill.filePath)}`,
+        skill,
+    ]));
+    const currentSkillKeys = new Map(workspace.skills.map((skill) => [
+        `${skill.name}\u0000${resolve(skill.filePath)}`,
+        skill,
+    ]));
+    for (const [key, skill] of previousSkillKeys) {
+        if (currentSkillKeys.has(key))
+            continue;
+        sections.push(`Skill metadata removed: skills://${encodeURIComponent(skill.name)}`);
+    }
+    for (const [key, skill] of currentSkillKeys) {
+        if (previousSkillKeys.has(key))
+            continue;
+        sections.push(`Skill metadata added: skills://${encodeURIComponent(skill.name)}\n+ description: ${skill.description}`);
+    }
+    if (JSON.stringify(previousSkillDiagnostics) !== JSON.stringify(workspace.skillDiagnostics)) {
+        if (workspace.skillDiagnostics.length === 0) {
+            sections.push("Skill diagnostics cleared.");
+        }
+        else {
+            sections.push([
+                "Current Skill diagnostics:",
+                ...workspace.skillDiagnostics.map((diagnostic) => `- ${diagnostic.type}: ${redactSkillDiagnosticMessage(diagnostic)}`),
+            ].join("\n"));
+        }
+    }
+    return sections.join("\n\n");
+}
 async function readSystemInstructions(path) {
     try {
         return await readFile(path, "utf8");

package/dist/workspaces/relay/auth/cli-test-support.js

@@ -0,0 +1,22 @@
+export async function runCliWithScriptedPseudoTerminal(args, env, steps, timeoutMs = 20_000) {
+    const nodePty = await import("node-pty");
+    const ptyEnv = Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== undefined));
+    const child = nodePty.spawn(process.execPath, ["--import", "tsx", "src/cli.ts", ...args], { cwd: process.cwd(), env: ptyEnv, name: "xterm-256color", cols: 80, rows: 24 });
+    let terminalOutput = "";
+    let stepIndex = 0;
+    const dataDisposable = child.onData((chunk) => {
+        terminalOutput += chunk;
+        const step = steps[stepIndex];
+        if (step && step.match.test(terminalOutput)) {
+            stepIndex += 1;
+            child.write(`${step.input}\r`);
+        }
+    });
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    const status = await new Promise((resolve) => {
+        child.onExit(({ exitCode }) => resolve(exitCode));
+    });
+    clearTimeout(timer);
+    dataDisposable.dispose();
+    return { status, output: terminalOutput };
+}