@agiflowai/aicode-utils 1.0.14 → 1.0.16

package/dist/index.cjs

@@ -191,16 +191,41 @@ const log = {
 var TemplatesManagerService = class TemplatesManagerService {
 	static SCAFFOLD_CONFIG_FILE = "scaffold.yaml";
 	static TEMPLATES_FOLDER = "templates";
+	static TOOLKIT_FOLDER = ".toolkit";
+	static SETTINGS_FILE = "settings.yaml";
+	static SETTINGS_LOCAL_FILE = "settings.local.yaml";
 	static TOOLKIT_CONFIG_FILE = "toolkit.yaml";
 	/**
+	* Recursively merge two plain objects. Primitive and array values in `local`
+	* replace those in `base`; plain-object values are merged recursively.
+	*/
+	static deepMerge(base, local) {
+		const result = { ...base };
+		for (const [key, localValue] of Object.entries(local)) {
+			const baseValue = result[key];
+			if (localValue !== null && typeof localValue === "object" && !Array.isArray(localValue) && baseValue !== null && typeof baseValue === "object" && !Array.isArray(baseValue)) result[key] = TemplatesManagerService.deepMerge(baseValue, localValue);
+			else result[key] = localValue;
+		}
+		return result;
+	}
+	/**
+	* Deep-merge two ToolkitConfig objects. Plain-object values are merged
+	* recursively; primitives and arrays in `local` replace those in `base`.
+	* This allows settings.local.yaml to override a single leaf key (e.g.
+	* scaffold-mcp.mcp-serve.fallbackTool) without wiping sibling keys.
+	*/
+	static mergeToolkitConfigs(base, local) {
+		return TemplatesManagerService.deepMerge(base, local);
+	}
+	/**
 	* Find the templates directory by searching upwards from the starting path.
 	*
 	* Algorithm:
 	* 1. Start from the provided path (default: current working directory)
 	* 2. Search upwards to find the workspace root (where .git exists or filesystem root)
-	* 3. Check if toolkit.yaml exists at workspace root
-	*    - If yes, read templatesPath from toolkit.yaml
-	*    - If no, default to 'templates' folder in workspace root
+	* 3. Read toolkit config (checks .toolkit/settings.yaml, then toolkit.yaml)
+	*    - If config has templatesPath, use it
+	*    - If no config, default to 'templates' folder in workspace root
 	* 4. Verify the templates directory exists
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
@@ -208,16 +233,11 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static async findTemplatesPath(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (await pathExists(toolkitConfigPath)) {
-			const yaml = await import("js-yaml");
-			const content = await node_fs_promises.readFile(toolkitConfigPath, "utf-8");
-			const config = yaml.load(content);
-			if (config?.templatesPath) {
-				const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.join(workspaceRoot, config.templatesPath);
-				if (await pathExists(templatesPath$1)) return templatesPath$1;
-				else return null;
-			}
+		const config = await TemplatesManagerService.readToolkitConfig(startPath);
+		if (config?.templatesPath) {
+			const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.join(workspaceRoot, config.templatesPath);
+			if (await pathExists(templatesPath$1)) return templatesPath$1;
+			return null;
 		}
 		const templatesPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
 		if (await pathExists(templatesPath)) return templatesPath;
@@ -244,16 +264,11 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static findTemplatesPathSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (pathExistsSync(toolkitConfigPath)) {
-			const yaml = require("js-yaml");
-			const content = (0, node_fs.readFileSync)(toolkitConfigPath, "utf-8");
-			const config = yaml.load(content);
-			if (config?.templatesPath) {
-				const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.join(workspaceRoot, config.templatesPath);
-				if (pathExistsSync(templatesPath$1)) return templatesPath$1;
-				else return null;
-			}
+		const config = TemplatesManagerService.readToolkitConfigSync(startPath);
+		if (config?.templatesPath) {
+			const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.join(workspaceRoot, config.templatesPath);
+			if (pathExistsSync(templatesPath$1)) return templatesPath$1;
+			return null;
 		}
 		const templatesPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
 		if (pathExistsSync(templatesPath)) return templatesPath;
@@ -294,44 +309,80 @@ var TemplatesManagerService = class TemplatesManagerService {
 		return TemplatesManagerService.TEMPLATES_FOLDER;
 	}
 	/**
-	* Read toolkit.yaml configuration from workspace root
+	* Read toolkit configuration from workspace root.
+	*
+	* Priority order:
+	* 1. .toolkit/settings.yaml (new location)
+	* 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+	* 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	* @returns The toolkit configuration object or null if not found
 	*/
 	static async readToolkitConfig(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!await pathExists(toolkitConfigPath)) return null;
 		const yaml = await import("js-yaml");
-		const content = await node_fs_promises.readFile(toolkitConfigPath, "utf-8");
+		const toolkitFolder = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = node_path.default.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		const settingsLocalPath = node_path.default.join(toolkitFolder, TemplatesManagerService.SETTINGS_LOCAL_FILE);
+		if (await pathExists(settingsPath)) {
+			const baseContent = await node_fs_promises.readFile(settingsPath, "utf-8");
+			const base = yaml.load(baseContent);
+			if (await pathExists(settingsLocalPath)) {
+				const localContent = await node_fs_promises.readFile(settingsLocalPath, "utf-8");
+				const local = yaml.load(localContent);
+				return TemplatesManagerService.mergeToolkitConfigs(base, local);
+			}
+			return base;
+		}
+		const legacyConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!await pathExists(legacyConfigPath)) return null;
+		const content = await node_fs_promises.readFile(legacyConfigPath, "utf-8");
 		return yaml.load(content);
 	}
 	/**
-	* Read toolkit.yaml configuration from workspace root (sync)
+	* Read toolkit configuration from workspace root (sync).
+	*
+	* Priority order:
+	* 1. .toolkit/settings.yaml (new location)
+	* 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+	* 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	* @returns The toolkit configuration object or null if not found
 	*/
 	static readToolkitConfigSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!pathExistsSync(toolkitConfigPath)) return null;
 		const yaml = require("js-yaml");
-		const content = (0, node_fs.readFileSync)(toolkitConfigPath, "utf-8");
-		return yaml.load(content);
+		const toolkitFolder = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = node_path.default.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		const settingsLocalPath = node_path.default.join(toolkitFolder, TemplatesManagerService.SETTINGS_LOCAL_FILE);
+		if (pathExistsSync(settingsPath)) {
+			const base = yaml.load((0, node_fs.readFileSync)(settingsPath, "utf-8"));
+			if (pathExistsSync(settingsLocalPath)) {
+				const local = yaml.load((0, node_fs.readFileSync)(settingsLocalPath, "utf-8"));
+				return TemplatesManagerService.mergeToolkitConfigs(base, local);
+			}
+			return base;
+		}
+		const legacyConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!pathExistsSync(legacyConfigPath)) return null;
+		return yaml.load((0, node_fs.readFileSync)(legacyConfigPath, "utf-8"));
 	}
 	/**
-	* Write toolkit.yaml configuration to workspace root
+	* Write toolkit configuration to .toolkit/settings.yaml.
+	* Creates the .toolkit directory if it does not exist.
 	*
 	* @param config - The toolkit configuration to write
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	*/
 	static async writeToolkitConfig(config, startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		const toolkitFolder = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = node_path.default.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		await node_fs_promises.mkdir(toolkitFolder, { recursive: true });
 		const content = (await import("js-yaml")).dump(config, { indent: 2 });
-		await node_fs_promises.writeFile(toolkitConfigPath, content, "utf-8");
+		await node_fs_promises.writeFile(settingsPath, content, "utf-8");
 	}
 	/**
 	* Get the workspace root directory

package/dist/index.d.cts

@@ -47,82 +47,332 @@ interface NxProjectJson {
 //#region src/types/index.d.ts
 
 /**
- * Toolkit configuration from toolkit.yaml
+ * Configuration for the scaffold-mcp mcp-serve command.
+ * Keys map 1-to-1 with CLI flags (camelCase).
+ */
+interface McpServeConfig {
+  /** Transport type. Default: stdio. */
+  type?: 'stdio' | 'http' | 'sse';
+  /** Port for http/sse transport. Default: 3000. */
+  port?: number;
+  /** Host to bind for http/sse transport. Default: localhost. */
+  host?: string;
+  /** Enable admin tools such as generate-boilerplate. Default: false. */
+  adminEnable?: boolean;
+  /** Render prompts with skill front matter for Claude Code. Default: false. */
+  promptAsSkill?: boolean;
+  /** Fallback LLM tool used when scaffold-mcp needs AI assistance. */
+  fallbackTool?: string;
+  /** Config passed to the fallback LLM tool. */
+  fallbackToolConfig?: Record<string, unknown>;
+  /** Extra CLI args merged into the mcp-serve command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Configuration for a single hook method invocation.
+ * Keys use kebab-case matching the adapter/CLI convention.
+ */
+interface HookMethodConfig {
+  /** LLM tool to invoke for this hook method (e.g. claude-code, gemini-cli). */
+  'llm-tool'?: string;
+  /** Config object forwarded to the LLM tool (e.g. { model: 'gemini-2.0-flash' }). */
+  'tool-config'?: Record<string, unknown>;
+  /** Fallback LLM tool used when the primary tool is unavailable. */
+  'fallback-tool'?: string;
+  /** Config object forwarded to the fallback LLM tool. */
+  'fallback-tool-config'?: Record<string, unknown>;
+  /** Extra CLI args appended to the generated hook command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Per-method configuration for a specific agent.
+ */
+interface HookAgentConfig {
+  /** Config applied when the agent invokes the PreToolUse hook. */
+  preToolUse?: HookMethodConfig;
+  /** Config applied when the agent invokes the PostToolUse hook. */
+  postToolUse?: HookMethodConfig;
+  /** Config applied when the agent invokes the Stop hook. */
+  stop?: HookMethodConfig;
+  /** Config applied when the agent invokes the UserPromptSubmit hook. */
+  userPromptSubmit?: HookMethodConfig;
+  /** Config applied when the agent invokes the TaskCompleted hook. */
+  taskCompleted?: HookMethodConfig;
+}
+/**
+ * Hook configuration keyed by agent name.
+ */
+interface HookConfig {
+  /** Hook config for Claude Code agent. */
+  'claude-code'?: HookAgentConfig;
+  /** Hook config for Gemini CLI agent. */
+  'gemini-cli'?: HookAgentConfig;
+}
+/**
+ * Top-level scaffold-mcp configuration block.
+ */
+interface ScaffoldMcpConfig {
+  /** Defaults for the `scaffold-mcp mcp-serve` command. */
+  'mcp-serve'?: McpServeConfig;
+  /** Hook method defaults keyed by agent name. */
+  hook?: HookConfig;
+}
+/**
+ * Configuration for the architect-mcp mcp-serve command.
+ * Keys map 1-to-1 with CLI flags (camelCase).
+ */
+interface ArchitectMcpServeConfig {
+  /** Transport type. Default: stdio. */
+  type?: 'stdio' | 'http' | 'sse';
+  /** Port for http/sse transport. Default: 3000. */
+  port?: number;
+  /** Host to bind for http/sse transport. Default: localhost. */
+  host?: string;
+  /** Enable admin tools such as add-design-pattern and add-rule. Default: false. */
+  adminEnable?: boolean;
+  /** Fallback LLM tool used for both design-pattern and review operations. */
+  fallbackTool?: string;
+  /** Config passed to the fallback LLM tool. */
+  fallbackToolConfig?: Record<string, unknown>;
+  /** LLM tool used specifically for get-file-design-pattern analysis. */
+  designPatternTool?: string;
+  /** Config passed to the design-pattern LLM tool. */
+  designPatternToolConfig?: Record<string, unknown>;
+  /** LLM tool used specifically for review-code-change analysis. */
+  reviewTool?: string;
+  /** Config passed to the review LLM tool. */
+  reviewToolConfig?: Record<string, unknown>;
+  /** Extra CLI args merged into the mcp-serve command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Configuration for a single architect-mcp hook method invocation.
+ * Keys use kebab-case matching the adapter/CLI convention.
+ */
+interface ArchitectHookMethodConfig {
+  /** LLM tool to invoke for this hook method. */
+  'llm-tool'?: string;
+  /** Config object forwarded to the LLM tool. */
+  'tool-config'?: Record<string, unknown>;
+  /** Extra CLI args appended to the generated hook command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Per-method configuration for a specific agent (architect-mcp).
+ * Only preToolUse and postToolUse are supported.
+ */
+interface ArchitectHookAgentConfig {
+  /** Config applied when the agent invokes the PreToolUse hook. */
+  preToolUse?: ArchitectHookMethodConfig;
+  /** Config applied when the agent invokes the PostToolUse hook. */
+  postToolUse?: ArchitectHookMethodConfig;
+}
+/**
+ * Hook configuration keyed by agent name (architect-mcp).
+ */
+interface ArchitectHookConfig {
+  /** Hook config for Claude Code agent. */
+  'claude-code'?: ArchitectHookAgentConfig;
+  /** Hook config for Gemini CLI agent. */
+  'gemini-cli'?: ArchitectHookAgentConfig;
+}
+/**
+ * Top-level architect-mcp configuration block.
+ */
+interface ArchitectMcpConfig {
+  /** Defaults for the `architect-mcp mcp-serve` command. */
+  'mcp-serve'?: ArchitectMcpServeConfig;
+  /** Hook method defaults keyed by agent name. */
+  hook?: ArchitectHookConfig;
+}
+/**
+ * Toolkit configuration from .toolkit/settings.yaml (or legacy toolkit.yaml)
  */
 interface ToolkitConfig {
+  /** Config schema version (e.g. '1.0'). */
   version?: string;
+  /** Path to the scaffold templates directory, relative to workspace root. */
   templatesPath?: string;
+  /** Project structure type: monolith (single app) or monorepo (multiple packages). */
   projectType?: 'monolith' | 'monorepo';
+  /** Active template name (monolith only — monorepo reads from project.json). */
   sourceTemplate?: string;
+  /** scaffold-mcp server and hook configuration. */
+  'scaffold-mcp'?: ScaffoldMcpConfig;
+  /** architect-mcp server and hook configuration. */
+  'architect-mcp'?: ArchitectMcpConfig;
 }
 /**
  * Project configuration from project.json
  */
 interface ProjectConfig {
+  /** Package/project name as declared in project.json. */
   name: string;
+  /** Root directory of the project, relative to workspace root. */
   root: string;
+  /** Template this project was scaffolded from. */
   sourceTemplate?: string;
+  /** Project type as declared in project.json (e.g. 'application' or 'library'). */
   projectType?: string;
 }
 /**
  * Scaffold template include configuration
  */
 interface ParsedInclude {
+  /** Absolute path of the source template file. */
   sourcePath: string;
+  /** Absolute path of the destination file in the target directory. */
   targetPath: string;
+  /** Conditions that must be satisfied for this include to be applied. */
   conditions?: Record<string, string>;
 }
 /**
  * Result of a scaffold operation
  */
 interface ScaffoldResult {
+  /** Whether the scaffold operation completed without errors. */
   success: boolean;
+  /** Human-readable summary of the operation outcome. */
   message: string;
+  /** Non-fatal warnings collected during the operation. */
   warnings?: string[];
+  /** Paths of files that were newly created. */
   createdFiles?: string[];
+  /** Paths of files that already existed and were not overwritten. */
   existingFiles?: string[];
 }
+/**
+ * Minimal stat result returned by IFileSystemService.stat.
+ */
+interface FileStat {
+  /**
+   * @returns True when the path is a directory.
+   */
+  isDirectory(): boolean;
+  /**
+   * @returns True when the path is a regular file.
+   */
+  isFile(): boolean;
+}
 /**
  * Abstract interface for file system operations
  */
 interface IFileSystemService {
+  /**
+   * Check whether a path exists on disk.
+   * @param path - Absolute path to check.
+   * @returns True when the path exists.
+   */
   pathExists(path: string): Promise<boolean>;
+  /**
+   * Read a file as text.
+   * @param path - Absolute path of the file.
+   * @param encoding - Character encoding (default: utf-8).
+   * @returns File contents as a string.
+   */
   readFile(path: string, encoding?: BufferEncoding): Promise<string>;
-  readJson(path: string): Promise<any>;
+  /**
+   * Read and parse a JSON file. Returns unknown — callers must narrow the type.
+   * @param path - Absolute path of the JSON file.
+   * @returns Parsed value with type unknown.
+   */
+  readJson(path: string): Promise<unknown>;
+  /**
+   * Write text content to a file.
+   * @param path - Absolute path of the target file.
+   * @param content - Text to write.
+   * @param encoding - Character encoding (default: utf-8).
+   * @returns Promise that resolves when the file is written.
+   */
   writeFile(path: string, content: string, encoding?: BufferEncoding): Promise<void>;
+  /**
+   * Create a directory and all parent directories.
+   * @param path - Absolute path of the directory to create.
+   * @returns Promise that resolves when the directory exists.
+   */
   ensureDir(path: string): Promise<void>;
+  /**
+   * Copy a file or directory from src to dest.
+   * @param src - Absolute source path.
+   * @param dest - Absolute destination path.
+   * @returns Promise that resolves when the copy is complete.
+   */
   copy(src: string, dest: string): Promise<void>;
+  /**
+   * List the entries of a directory.
+   * @param path - Absolute path of the directory.
+   * @returns Array of entry names (not full paths).
+   */
   readdir(path: string): Promise<string[]>;
-  stat(path: string): Promise<{
-    isDirectory(): boolean;
-    isFile(): boolean;
-  }>;
+  /**
+   * Return stat info for a path.
+   * @param path - Absolute path to stat.
+   * @returns FileStat with isDirectory and isFile helpers.
+   */
+  stat(path: string): Promise<FileStat>;
 }
 /**
  * Abstract interface for variable replacement in templates
  */
 interface IVariableReplacementService {
-  processFilesForVariableReplacement(dirPath: string, variables: Record<string, any>): Promise<void>;
-  replaceVariablesInFile(filePath: string, variables: Record<string, any>): Promise<void>;
+  /**
+   * Walk dirPath and apply variable substitution to every non-binary file.
+   * @param dirPath - Directory to process recursively.
+   * @param variables - Key/value pairs used for substitution.
+   * @returns Promise that resolves when all files have been processed.
+   */
+  processFilesForVariableReplacement(dirPath: string, variables: Record<string, unknown>): Promise<void>;
+  /**
+   * Apply variable substitution to a single file.
+   * @param filePath - File to process.
+   * @param variables - Key/value pairs used for substitution.
+   * @returns Promise that resolves when the file has been processed.
+   */
+  replaceVariablesInFile(filePath: string, variables: Record<string, unknown>): Promise<void>;
+  /**
+   * Checks if a file should be treated as a binary (non-text) file.
+   * @param filePath - Path to check.
+   * @returns True if the file is binary.
+   */
   isBinaryFile(filePath: string): boolean;
 }
 /**
- * Context object passed to generator functions
+ * Context object passed to generator functions.
+ * Bundles all dependencies needed to produce scaffold output.
  */
 interface GeneratorContext {
-  variables: Record<string, any>;
-  config: any;
+  /** Template variables resolved for the current scaffold operation. */
+  variables: Record<string, unknown>;
+  /** Raw scaffold configuration loaded from scaffold.yaml. */
+  config: unknown;
+  /** Absolute path of the directory where output files will be written. */
   targetPath: string;
+  /** Absolute path of the source template directory. */
   templatePath: string;
+  /** File-system abstraction used for all I/O inside generators. */
   fileSystem: IFileSystemService;
-  scaffoldConfigLoader: any;
+  /** Loader for scaffold config files — typed as unknown to avoid circular deps. */
+  scaffoldConfigLoader: unknown;
+  /** Variable-replacement service injected to avoid circular imports. */
   variableReplacer: IVariableReplacementService;
-  ScaffoldProcessingService: any;
+  /** ScaffoldProcessingService constructor — passed to avoid circular imports. */
+  ScaffoldProcessingService: new (...args: unknown[]) => unknown;
+  /**
+   * Return the workspace root path.
+   * @returns Absolute path of the workspace root.
+   */
   getRootPath: () => string;
+  /**
+   * Return the absolute path of a project relative to the workspace root.
+   * @param projectPath - Project path relative to the workspace root.
+   * @returns Absolute path of the project.
+   */
   getProjectPath: (projectPath: string) => string;
 }
 /**
- * Type definition for generator functions
+ * Type definition for generator functions.
+ * @param context - The generator context bundling all scaffold dependencies.
+ * @returns A promise resolving to the scaffold result.
  */
 type GeneratorFunction = (context: GeneratorContext) => Promise<ScaffoldResult>;
 //#endregion
@@ -254,16 +504,31 @@ declare class ScaffoldProcessingService {
 declare class TemplatesManagerService {
   private static SCAFFOLD_CONFIG_FILE;
   private static TEMPLATES_FOLDER;
+  private static TOOLKIT_FOLDER;
+  private static SETTINGS_FILE;
+  private static SETTINGS_LOCAL_FILE;
   private static TOOLKIT_CONFIG_FILE;
+  /**
+   * Recursively merge two plain objects. Primitive and array values in `local`
+   * replace those in `base`; plain-object values are merged recursively.
+   */
+  private static deepMerge;
+  /**
+   * Deep-merge two ToolkitConfig objects. Plain-object values are merged
+   * recursively; primitives and arrays in `local` replace those in `base`.
+   * This allows settings.local.yaml to override a single leaf key (e.g.
+   * scaffold-mcp.mcp-serve.fallbackTool) without wiping sibling keys.
+   */
+  private static mergeToolkitConfigs;
   /**
    * Find the templates directory by searching upwards from the starting path.
    *
    * Algorithm:
    * 1. Start from the provided path (default: current working directory)
    * 2. Search upwards to find the workspace root (where .git exists or filesystem root)
-   * 3. Check if toolkit.yaml exists at workspace root
-   *    - If yes, read templatesPath from toolkit.yaml
-   *    - If no, default to 'templates' folder in workspace root
+   * 3. Read toolkit config (checks .toolkit/settings.yaml, then toolkit.yaml)
+   *    - If config has templatesPath, use it
+   *    - If no config, default to 'templates' folder in workspace root
    * 4. Verify the templates directory exists
    *
    * @param startPath - The path to start searching from (defaults to process.cwd())
@@ -302,21 +567,32 @@ declare class TemplatesManagerService {
    */
   static getTemplatesFolderName(): string;
   /**
-   * Read toolkit.yaml configuration from workspace root
+   * Read toolkit configuration from workspace root.
+   *
+   * Priority order:
+   * 1. .toolkit/settings.yaml (new location)
+   * 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+   * 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
    *
    * @param startPath - The path to start searching from (defaults to process.cwd())
    * @returns The toolkit configuration object or null if not found
    */
   static readToolkitConfig(startPath?: string): Promise<ToolkitConfig | null>;
   /**
-   * Read toolkit.yaml configuration from workspace root (sync)
+   * Read toolkit configuration from workspace root (sync).
+   *
+   * Priority order:
+   * 1. .toolkit/settings.yaml (new location)
+   * 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+   * 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
    *
    * @param startPath - The path to start searching from (defaults to process.cwd())
    * @returns The toolkit configuration object or null if not found
    */
   static readToolkitConfigSync(startPath?: string): ToolkitConfig | null;
   /**
-   * Write toolkit.yaml configuration to workspace root
+   * Write toolkit configuration to .toolkit/settings.yaml.
+   * Creates the .toolkit directory if it does not exist.
    *
    * @param config - The toolkit configuration to write
    * @param startPath - The path to start searching from (defaults to process.cwd())
@@ -680,4 +956,4 @@ interface ProjectTypeDetectionResult {
  */
 declare function detectProjectType(workspaceRoot: string): Promise<ProjectTypeDetectionResult>;
 //#endregion
-export { ConfigSource, GeneratorContext, GeneratorFunction, GitHubDirectoryEntry, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedGitHubUrl, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, accessSync, cloneRepository, cloneSubdirectory, copy, detectProjectType, ensureDir, fetchGitHubDirectoryContents, findWorkspaceRoot, generateStableId, gitInit, icons, log, logger, messages, mkdir, mkdirSync, move, parseGitHubUrl, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, sections, stat, statSync, writeFile, writeFileSync };
+export { ArchitectHookAgentConfig, ArchitectHookConfig, ArchitectHookMethodConfig, ArchitectMcpConfig, ArchitectMcpServeConfig, ConfigSource, FileStat, GeneratorContext, GeneratorFunction, GitHubDirectoryEntry, HookAgentConfig, HookConfig, HookMethodConfig, IFileSystemService, IVariableReplacementService, McpServeConfig, type NxProjectJson, ParsedGitHubUrl, ParsedInclude, ProjectConfig, ProjectConfigResolver, type ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldMcpConfig, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, accessSync, cloneRepository, cloneSubdirectory, copy, detectProjectType, ensureDir, fetchGitHubDirectoryContents, findWorkspaceRoot, generateStableId, gitInit, icons, log, logger, messages, mkdir, mkdirSync, move, parseGitHubUrl, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, sections, stat, statSync, writeFile, writeFileSync };

package/dist/index.d.mts

@@ -47,82 +47,332 @@ interface NxProjectJson {
 //#region src/types/index.d.ts
 
 /**
- * Toolkit configuration from toolkit.yaml
+ * Configuration for the scaffold-mcp mcp-serve command.
+ * Keys map 1-to-1 with CLI flags (camelCase).
+ */
+interface McpServeConfig {
+  /** Transport type. Default: stdio. */
+  type?: 'stdio' | 'http' | 'sse';
+  /** Port for http/sse transport. Default: 3000. */
+  port?: number;
+  /** Host to bind for http/sse transport. Default: localhost. */
+  host?: string;
+  /** Enable admin tools such as generate-boilerplate. Default: false. */
+  adminEnable?: boolean;
+  /** Render prompts with skill front matter for Claude Code. Default: false. */
+  promptAsSkill?: boolean;
+  /** Fallback LLM tool used when scaffold-mcp needs AI assistance. */
+  fallbackTool?: string;
+  /** Config passed to the fallback LLM tool. */
+  fallbackToolConfig?: Record<string, unknown>;
+  /** Extra CLI args merged into the mcp-serve command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Configuration for a single hook method invocation.
+ * Keys use kebab-case matching the adapter/CLI convention.
+ */
+interface HookMethodConfig {
+  /** LLM tool to invoke for this hook method (e.g. claude-code, gemini-cli). */
+  'llm-tool'?: string;
+  /** Config object forwarded to the LLM tool (e.g. { model: 'gemini-2.0-flash' }). */
+  'tool-config'?: Record<string, unknown>;
+  /** Fallback LLM tool used when the primary tool is unavailable. */
+  'fallback-tool'?: string;
+  /** Config object forwarded to the fallback LLM tool. */
+  'fallback-tool-config'?: Record<string, unknown>;
+  /** Extra CLI args appended to the generated hook command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Per-method configuration for a specific agent.
+ */
+interface HookAgentConfig {
+  /** Config applied when the agent invokes the PreToolUse hook. */
+  preToolUse?: HookMethodConfig;
+  /** Config applied when the agent invokes the PostToolUse hook. */
+  postToolUse?: HookMethodConfig;
+  /** Config applied when the agent invokes the Stop hook. */
+  stop?: HookMethodConfig;
+  /** Config applied when the agent invokes the UserPromptSubmit hook. */
+  userPromptSubmit?: HookMethodConfig;
+  /** Config applied when the agent invokes the TaskCompleted hook. */
+  taskCompleted?: HookMethodConfig;
+}
+/**
+ * Hook configuration keyed by agent name.
+ */
+interface HookConfig {
+  /** Hook config for Claude Code agent. */
+  'claude-code'?: HookAgentConfig;
+  /** Hook config for Gemini CLI agent. */
+  'gemini-cli'?: HookAgentConfig;
+}
+/**
+ * Top-level scaffold-mcp configuration block.
+ */
+interface ScaffoldMcpConfig {
+  /** Defaults for the `scaffold-mcp mcp-serve` command. */
+  'mcp-serve'?: McpServeConfig;
+  /** Hook method defaults keyed by agent name. */
+  hook?: HookConfig;
+}
+/**
+ * Configuration for the architect-mcp mcp-serve command.
+ * Keys map 1-to-1 with CLI flags (camelCase).
+ */
+interface ArchitectMcpServeConfig {
+  /** Transport type. Default: stdio. */
+  type?: 'stdio' | 'http' | 'sse';
+  /** Port for http/sse transport. Default: 3000. */
+  port?: number;
+  /** Host to bind for http/sse transport. Default: localhost. */
+  host?: string;
+  /** Enable admin tools such as add-design-pattern and add-rule. Default: false. */
+  adminEnable?: boolean;
+  /** Fallback LLM tool used for both design-pattern and review operations. */
+  fallbackTool?: string;
+  /** Config passed to the fallback LLM tool. */
+  fallbackToolConfig?: Record<string, unknown>;
+  /** LLM tool used specifically for get-file-design-pattern analysis. */
+  designPatternTool?: string;
+  /** Config passed to the design-pattern LLM tool. */
+  designPatternToolConfig?: Record<string, unknown>;
+  /** LLM tool used specifically for review-code-change analysis. */
+  reviewTool?: string;
+  /** Config passed to the review LLM tool. */
+  reviewToolConfig?: Record<string, unknown>;
+  /** Extra CLI args merged into the mcp-serve command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Configuration for a single architect-mcp hook method invocation.
+ * Keys use kebab-case matching the adapter/CLI convention.
+ */
+interface ArchitectHookMethodConfig {
+  /** LLM tool to invoke for this hook method. */
+  'llm-tool'?: string;
+  /** Config object forwarded to the LLM tool. */
+  'tool-config'?: Record<string, unknown>;
+  /** Extra CLI args appended to the generated hook command (key → --key value). */
+  args?: Record<string, string | boolean | number>;
+}
+/**
+ * Per-method configuration for a specific agent (architect-mcp).
+ * Only preToolUse and postToolUse are supported.
+ */
+interface ArchitectHookAgentConfig {
+  /** Config applied when the agent invokes the PreToolUse hook. */
+  preToolUse?: ArchitectHookMethodConfig;
+  /** Config applied when the agent invokes the PostToolUse hook. */
+  postToolUse?: ArchitectHookMethodConfig;
+}
+/**
+ * Hook configuration keyed by agent name (architect-mcp).
+ */
+interface ArchitectHookConfig {
+  /** Hook config for Claude Code agent. */
+  'claude-code'?: ArchitectHookAgentConfig;
+  /** Hook config for Gemini CLI agent. */
+  'gemini-cli'?: ArchitectHookAgentConfig;
+}
+/**
+ * Top-level architect-mcp configuration block.
+ */
+interface ArchitectMcpConfig {
+  /** Defaults for the `architect-mcp mcp-serve` command. */
+  'mcp-serve'?: ArchitectMcpServeConfig;
+  /** Hook method defaults keyed by agent name. */
+  hook?: ArchitectHookConfig;
+}
+/**
+ * Toolkit configuration from .toolkit/settings.yaml (or legacy toolkit.yaml)
  */
 interface ToolkitConfig {
+  /** Config schema version (e.g. '1.0'). */
   version?: string;
+  /** Path to the scaffold templates directory, relative to workspace root. */
   templatesPath?: string;
+  /** Project structure type: monolith (single app) or monorepo (multiple packages). */
   projectType?: 'monolith' | 'monorepo';
+  /** Active template name (monolith only — monorepo reads from project.json). */
   sourceTemplate?: string;
+  /** scaffold-mcp server and hook configuration. */
+  'scaffold-mcp'?: ScaffoldMcpConfig;
+  /** architect-mcp server and hook configuration. */
+  'architect-mcp'?: ArchitectMcpConfig;
 }
 /**
  * Project configuration from project.json
  */
 interface ProjectConfig {
+  /** Package/project name as declared in project.json. */
   name: string;
+  /** Root directory of the project, relative to workspace root. */
   root: string;
+  /** Template this project was scaffolded from. */
   sourceTemplate?: string;
+  /** Project type as declared in project.json (e.g. 'application' or 'library'). */
   projectType?: string;
 }
 /**
  * Scaffold template include configuration
  */
 interface ParsedInclude {
+  /** Absolute path of the source template file. */
   sourcePath: string;
+  /** Absolute path of the destination file in the target directory. */
   targetPath: string;
+  /** Conditions that must be satisfied for this include to be applied. */
   conditions?: Record<string, string>;
 }
 /**
  * Result of a scaffold operation
  */
 interface ScaffoldResult {
+  /** Whether the scaffold operation completed without errors. */
   success: boolean;
+  /** Human-readable summary of the operation outcome. */
   message: string;
+  /** Non-fatal warnings collected during the operation. */
   warnings?: string[];
+  /** Paths of files that were newly created. */
   createdFiles?: string[];
+  /** Paths of files that already existed and were not overwritten. */
   existingFiles?: string[];
 }
+/**
+ * Minimal stat result returned by IFileSystemService.stat.
+ */
+interface FileStat {
+  /**
+   * @returns True when the path is a directory.
+   */
+  isDirectory(): boolean;
+  /**
+   * @returns True when the path is a regular file.
+   */
+  isFile(): boolean;
+}
 /**
  * Abstract interface for file system operations
  */
 interface IFileSystemService {
+  /**
+   * Check whether a path exists on disk.
+   * @param path - Absolute path to check.
+   * @returns True when the path exists.
+   */
   pathExists(path: string): Promise<boolean>;
+  /**
+   * Read a file as text.
+   * @param path - Absolute path of the file.
+   * @param encoding - Character encoding (default: utf-8).
+   * @returns File contents as a string.
+   */
   readFile(path: string, encoding?: BufferEncoding): Promise<string>;
-  readJson(path: string): Promise<any>;
+  /**
+   * Read and parse a JSON file. Returns unknown — callers must narrow the type.
+   * @param path - Absolute path of the JSON file.
+   * @returns Parsed value with type unknown.
+   */
+  readJson(path: string): Promise<unknown>;
+  /**
+   * Write text content to a file.
+   * @param path - Absolute path of the target file.
+   * @param content - Text to write.
+   * @param encoding - Character encoding (default: utf-8).
+   * @returns Promise that resolves when the file is written.
+   */
   writeFile(path: string, content: string, encoding?: BufferEncoding): Promise<void>;
+  /**
+   * Create a directory and all parent directories.
+   * @param path - Absolute path of the directory to create.
+   * @returns Promise that resolves when the directory exists.
+   */
   ensureDir(path: string): Promise<void>;
+  /**
+   * Copy a file or directory from src to dest.
+   * @param src - Absolute source path.
+   * @param dest - Absolute destination path.
+   * @returns Promise that resolves when the copy is complete.
+   */
   copy(src: string, dest: string): Promise<void>;
+  /**
+   * List the entries of a directory.
+   * @param path - Absolute path of the directory.
+   * @returns Array of entry names (not full paths).
+   */
   readdir(path: string): Promise<string[]>;
-  stat(path: string): Promise<{
-    isDirectory(): boolean;
-    isFile(): boolean;
-  }>;
+  /**
+   * Return stat info for a path.
+   * @param path - Absolute path to stat.
+   * @returns FileStat with isDirectory and isFile helpers.
+   */
+  stat(path: string): Promise<FileStat>;
 }
 /**
  * Abstract interface for variable replacement in templates
  */
 interface IVariableReplacementService {
-  processFilesForVariableReplacement(dirPath: string, variables: Record<string, any>): Promise<void>;
-  replaceVariablesInFile(filePath: string, variables: Record<string, any>): Promise<void>;
+  /**
+   * Walk dirPath and apply variable substitution to every non-binary file.
+   * @param dirPath - Directory to process recursively.
+   * @param variables - Key/value pairs used for substitution.
+   * @returns Promise that resolves when all files have been processed.
+   */
+  processFilesForVariableReplacement(dirPath: string, variables: Record<string, unknown>): Promise<void>;
+  /**
+   * Apply variable substitution to a single file.
+   * @param filePath - File to process.
+   * @param variables - Key/value pairs used for substitution.
+   * @returns Promise that resolves when the file has been processed.
+   */
+  replaceVariablesInFile(filePath: string, variables: Record<string, unknown>): Promise<void>;
+  /**
+   * Checks if a file should be treated as a binary (non-text) file.
+   * @param filePath - Path to check.
+   * @returns True if the file is binary.
+   */
   isBinaryFile(filePath: string): boolean;
 }
 /**
- * Context object passed to generator functions
+ * Context object passed to generator functions.
+ * Bundles all dependencies needed to produce scaffold output.
  */
 interface GeneratorContext {
-  variables: Record<string, any>;
-  config: any;
+  /** Template variables resolved for the current scaffold operation. */
+  variables: Record<string, unknown>;
+  /** Raw scaffold configuration loaded from scaffold.yaml. */
+  config: unknown;
+  /** Absolute path of the directory where output files will be written. */
   targetPath: string;
+  /** Absolute path of the source template directory. */
   templatePath: string;
+  /** File-system abstraction used for all I/O inside generators. */
   fileSystem: IFileSystemService;
-  scaffoldConfigLoader: any;
+  /** Loader for scaffold config files — typed as unknown to avoid circular deps. */
+  scaffoldConfigLoader: unknown;
+  /** Variable-replacement service injected to avoid circular imports. */
   variableReplacer: IVariableReplacementService;
-  ScaffoldProcessingService: any;
+  /** ScaffoldProcessingService constructor — passed to avoid circular imports. */
+  ScaffoldProcessingService: new (...args: unknown[]) => unknown;
+  /**
+   * Return the workspace root path.
+   * @returns Absolute path of the workspace root.
+   */
   getRootPath: () => string;
+  /**
+   * Return the absolute path of a project relative to the workspace root.
+   * @param projectPath - Project path relative to the workspace root.
+   * @returns Absolute path of the project.
+   */
   getProjectPath: (projectPath: string) => string;
 }
 /**
- * Type definition for generator functions
+ * Type definition for generator functions.
+ * @param context - The generator context bundling all scaffold dependencies.
+ * @returns A promise resolving to the scaffold result.
  */
 type GeneratorFunction = (context: GeneratorContext) => Promise<ScaffoldResult>;
 //#endregion
@@ -254,16 +504,31 @@ declare class ScaffoldProcessingService {
 declare class TemplatesManagerService {
   private static SCAFFOLD_CONFIG_FILE;
   private static TEMPLATES_FOLDER;
+  private static TOOLKIT_FOLDER;
+  private static SETTINGS_FILE;
+  private static SETTINGS_LOCAL_FILE;
   private static TOOLKIT_CONFIG_FILE;
+  /**
+   * Recursively merge two plain objects. Primitive and array values in `local`
+   * replace those in `base`; plain-object values are merged recursively.
+   */
+  private static deepMerge;
+  /**
+   * Deep-merge two ToolkitConfig objects. Plain-object values are merged
+   * recursively; primitives and arrays in `local` replace those in `base`.
+   * This allows settings.local.yaml to override a single leaf key (e.g.
+   * scaffold-mcp.mcp-serve.fallbackTool) without wiping sibling keys.
+   */
+  private static mergeToolkitConfigs;
   /**
    * Find the templates directory by searching upwards from the starting path.
    *
    * Algorithm:
    * 1. Start from the provided path (default: current working directory)
    * 2. Search upwards to find the workspace root (where .git exists or filesystem root)
-   * 3. Check if toolkit.yaml exists at workspace root
-   *    - If yes, read templatesPath from toolkit.yaml
-   *    - If no, default to 'templates' folder in workspace root
+   * 3. Read toolkit config (checks .toolkit/settings.yaml, then toolkit.yaml)
+   *    - If config has templatesPath, use it
+   *    - If no config, default to 'templates' folder in workspace root
    * 4. Verify the templates directory exists
    *
    * @param startPath - The path to start searching from (defaults to process.cwd())
@@ -302,21 +567,32 @@ declare class TemplatesManagerService {
    */
   static getTemplatesFolderName(): string;
   /**
-   * Read toolkit.yaml configuration from workspace root
+   * Read toolkit configuration from workspace root.
+   *
+   * Priority order:
+   * 1. .toolkit/settings.yaml (new location)
+   * 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+   * 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
    *
    * @param startPath - The path to start searching from (defaults to process.cwd())
    * @returns The toolkit configuration object or null if not found
    */
   static readToolkitConfig(startPath?: string): Promise<ToolkitConfig | null>;
   /**
-   * Read toolkit.yaml configuration from workspace root (sync)
+   * Read toolkit configuration from workspace root (sync).
+   *
+   * Priority order:
+   * 1. .toolkit/settings.yaml (new location)
+   * 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+   * 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
    *
    * @param startPath - The path to start searching from (defaults to process.cwd())
    * @returns The toolkit configuration object or null if not found
    */
   static readToolkitConfigSync(startPath?: string): ToolkitConfig | null;
   /**
-   * Write toolkit.yaml configuration to workspace root
+   * Write toolkit configuration to .toolkit/settings.yaml.
+   * Creates the .toolkit directory if it does not exist.
    *
    * @param config - The toolkit configuration to write
    * @param startPath - The path to start searching from (defaults to process.cwd())
@@ -680,4 +956,4 @@ interface ProjectTypeDetectionResult {
  */
 declare function detectProjectType(workspaceRoot: string): Promise<ProjectTypeDetectionResult>;
 //#endregion
-export { ConfigSource, GeneratorContext, GeneratorFunction, type GitHubDirectoryEntry, IFileSystemService, IVariableReplacementService, NxProjectJson, type ParsedGitHubUrl, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, accessSync, cloneRepository, cloneSubdirectory, copy, detectProjectType, ensureDir, fetchGitHubDirectoryContents, findWorkspaceRoot, generateStableId, gitInit, icons, log, logger, messages, mkdir, mkdirSync, move, parseGitHubUrl, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, sections, stat, statSync, writeFile, writeFileSync };
+export { ArchitectHookAgentConfig, ArchitectHookConfig, ArchitectHookMethodConfig, ArchitectMcpConfig, ArchitectMcpServeConfig, ConfigSource, FileStat, GeneratorContext, GeneratorFunction, type GitHubDirectoryEntry, HookAgentConfig, HookConfig, HookMethodConfig, IFileSystemService, IVariableReplacementService, McpServeConfig, type NxProjectJson, type ParsedGitHubUrl, ParsedInclude, ProjectConfig, ProjectConfigResolver, type ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldMcpConfig, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, accessSync, cloneRepository, cloneSubdirectory, copy, detectProjectType, ensureDir, fetchGitHubDirectoryContents, findWorkspaceRoot, generateStableId, gitInit, icons, log, logger, messages, mkdir, mkdirSync, move, parseGitHubUrl, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, sections, stat, statSync, writeFile, writeFileSync };

package/dist/index.mjs

@@ -164,16 +164,41 @@ const log = {
 var TemplatesManagerService = class TemplatesManagerService {
 	static SCAFFOLD_CONFIG_FILE = "scaffold.yaml";
 	static TEMPLATES_FOLDER = "templates";
+	static TOOLKIT_FOLDER = ".toolkit";
+	static SETTINGS_FILE = "settings.yaml";
+	static SETTINGS_LOCAL_FILE = "settings.local.yaml";
 	static TOOLKIT_CONFIG_FILE = "toolkit.yaml";
 	/**
+	* Recursively merge two plain objects. Primitive and array values in `local`
+	* replace those in `base`; plain-object values are merged recursively.
+	*/
+	static deepMerge(base, local) {
+		const result = { ...base };
+		for (const [key, localValue] of Object.entries(local)) {
+			const baseValue = result[key];
+			if (localValue !== null && typeof localValue === "object" && !Array.isArray(localValue) && baseValue !== null && typeof baseValue === "object" && !Array.isArray(baseValue)) result[key] = TemplatesManagerService.deepMerge(baseValue, localValue);
+			else result[key] = localValue;
+		}
+		return result;
+	}
+	/**
+	* Deep-merge two ToolkitConfig objects. Plain-object values are merged
+	* recursively; primitives and arrays in `local` replace those in `base`.
+	* This allows settings.local.yaml to override a single leaf key (e.g.
+	* scaffold-mcp.mcp-serve.fallbackTool) without wiping sibling keys.
+	*/
+	static mergeToolkitConfigs(base, local) {
+		return TemplatesManagerService.deepMerge(base, local);
+	}
+	/**
 	* Find the templates directory by searching upwards from the starting path.
 	*
 	* Algorithm:
 	* 1. Start from the provided path (default: current working directory)
 	* 2. Search upwards to find the workspace root (where .git exists or filesystem root)
-	* 3. Check if toolkit.yaml exists at workspace root
-	*    - If yes, read templatesPath from toolkit.yaml
-	*    - If no, default to 'templates' folder in workspace root
+	* 3. Read toolkit config (checks .toolkit/settings.yaml, then toolkit.yaml)
+	*    - If config has templatesPath, use it
+	*    - If no config, default to 'templates' folder in workspace root
 	* 4. Verify the templates directory exists
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
@@ -181,16 +206,11 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static async findTemplatesPath(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (await pathExists(toolkitConfigPath)) {
-			const yaml$1 = await import("js-yaml");
-			const content = await fs.readFile(toolkitConfigPath, "utf-8");
-			const config = yaml$1.load(content);
-			if (config?.templatesPath) {
-				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
-				if (await pathExists(templatesPath$1)) return templatesPath$1;
-				else return null;
-			}
+		const config = await TemplatesManagerService.readToolkitConfig(startPath);
+		if (config?.templatesPath) {
+			const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
+			if (await pathExists(templatesPath$1)) return templatesPath$1;
+			return null;
 		}
 		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
 		if (await pathExists(templatesPath)) return templatesPath;
@@ -217,16 +237,11 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static findTemplatesPathSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (pathExistsSync(toolkitConfigPath)) {
-			const yaml$1 = __require("js-yaml");
-			const content = readFileSync$1(toolkitConfigPath, "utf-8");
-			const config = yaml$1.load(content);
-			if (config?.templatesPath) {
-				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
-				if (pathExistsSync(templatesPath$1)) return templatesPath$1;
-				else return null;
-			}
+		const config = TemplatesManagerService.readToolkitConfigSync(startPath);
+		if (config?.templatesPath) {
+			const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
+			if (pathExistsSync(templatesPath$1)) return templatesPath$1;
+			return null;
 		}
 		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
 		if (pathExistsSync(templatesPath)) return templatesPath;
@@ -267,44 +282,80 @@ var TemplatesManagerService = class TemplatesManagerService {
 		return TemplatesManagerService.TEMPLATES_FOLDER;
 	}
 	/**
-	* Read toolkit.yaml configuration from workspace root
+	* Read toolkit configuration from workspace root.
+	*
+	* Priority order:
+	* 1. .toolkit/settings.yaml (new location)
+	* 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+	* 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	* @returns The toolkit configuration object or null if not found
 	*/
 	static async readToolkitConfig(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!await pathExists(toolkitConfigPath)) return null;
 		const yaml$1 = await import("js-yaml");
-		const content = await fs.readFile(toolkitConfigPath, "utf-8");
+		const toolkitFolder = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = path.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		const settingsLocalPath = path.join(toolkitFolder, TemplatesManagerService.SETTINGS_LOCAL_FILE);
+		if (await pathExists(settingsPath)) {
+			const baseContent = await fs.readFile(settingsPath, "utf-8");
+			const base = yaml$1.load(baseContent);
+			if (await pathExists(settingsLocalPath)) {
+				const localContent = await fs.readFile(settingsLocalPath, "utf-8");
+				const local = yaml$1.load(localContent);
+				return TemplatesManagerService.mergeToolkitConfigs(base, local);
+			}
+			return base;
+		}
+		const legacyConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!await pathExists(legacyConfigPath)) return null;
+		const content = await fs.readFile(legacyConfigPath, "utf-8");
 		return yaml$1.load(content);
 	}
 	/**
-	* Read toolkit.yaml configuration from workspace root (sync)
+	* Read toolkit configuration from workspace root (sync).
+	*
+	* Priority order:
+	* 1. .toolkit/settings.yaml (new location)
+	* 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+	* 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	* @returns The toolkit configuration object or null if not found
 	*/
 	static readToolkitConfigSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!pathExistsSync(toolkitConfigPath)) return null;
 		const yaml$1 = __require("js-yaml");
-		const content = readFileSync$1(toolkitConfigPath, "utf-8");
-		return yaml$1.load(content);
+		const toolkitFolder = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = path.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		const settingsLocalPath = path.join(toolkitFolder, TemplatesManagerService.SETTINGS_LOCAL_FILE);
+		if (pathExistsSync(settingsPath)) {
+			const base = yaml$1.load(readFileSync$1(settingsPath, "utf-8"));
+			if (pathExistsSync(settingsLocalPath)) {
+				const local = yaml$1.load(readFileSync$1(settingsLocalPath, "utf-8"));
+				return TemplatesManagerService.mergeToolkitConfigs(base, local);
+			}
+			return base;
+		}
+		const legacyConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!pathExistsSync(legacyConfigPath)) return null;
+		return yaml$1.load(readFileSync$1(legacyConfigPath, "utf-8"));
 	}
 	/**
-	* Write toolkit.yaml configuration to workspace root
+	* Write toolkit configuration to .toolkit/settings.yaml.
+	* Creates the .toolkit directory if it does not exist.
 	*
 	* @param config - The toolkit configuration to write
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	*/
 	static async writeToolkitConfig(config, startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		const toolkitFolder = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = path.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		await fs.mkdir(toolkitFolder, { recursive: true });
 		const content = (await import("js-yaml")).dump(config, { indent: 2 });
-		await fs.writeFile(toolkitConfigPath, content, "utf-8");
+		await fs.writeFile(settingsPath, content, "utf-8");
 	}
 	/**
 	* Get the workspace root directory

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/aicode-utils",
   "description": "Shared utilities and types for AI-powered code generation, scaffolding, and analysis",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {