feat(help-skill): expose debug.log for agent self-diagnosis (#698)

* feat(help-skill): expose debug.log to gemini-scribe-help for self-diagnosis

Fixes #586

Add debug.log and debug.log.old as virtual resources on the bundled
gemini-scribe-help skill, gated on the fileLogging setting and on each
file actually existing on disk. The plugin state folder is otherwise
blocked by the standard read_file tool, so this skill is the supported
path for the agent to read its own logs when diagnosing user-reported
issues.

Also rewrite the help-skill description so diagnostic-language prompts
("error", "bug", "what just happened", "check the debug log") trigger
activate_skill directly, instead of the agent first wandering through
find_files_by_name / read_file on the state folder.

* docs(help-skill): broaden 'Resource not found' guidance

Address CodeRabbit feedback on #698: the message can also surface when
file logging is on but the log file does not exist yet (e.g.
debug.log.old before any rotation), not only when Log to File is
disabled.

Author: allenhutchison

docs/reference/settings.md

@@ -193,8 +193,8 @@ Advanced settings for developers and power users. Access by clicking "Show Advan
   - Debug-level entries (`log()`, `debug()`) are only written when Debug Mode is also enabled
   - Log files are automatically rotated at 1 MB (previous log kept as `debug.log.old`)
   - Writes are batched and debounced to minimize I/O impact
-- **Use case**: Sharing diagnostic information in bug reports, or enabling the agent to read logs for self-diagnosis via vault tools
-- **Note**: Log files are stored in the plugin state folder and are automatically excluded from RAG indexing
+- **Use case**: Sharing diagnostic information in bug reports, or letting the agent self-diagnose issues via the bundled `gemini-scribe-help` skill (which exposes `debug.log` and `debug.log.old` as activatable resources only when this setting is on)
+- **Note**: Log files are stored in the plugin state folder and are automatically excluded from RAG indexing. The standard `read_file` tool blocks the state folder; the help skill is the supported path for the agent to read these logs.
 
 ### API Configuration
 

prompts/bundled-skills/gemini-scribe-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gemini-scribe-help
-description: Answer questions about Gemini Scribe plugin features, settings, and usage. Activate this skill when users ask how to use the plugin, configure settings, or troubleshoot issues.
+description: Answer questions about Gemini Scribe plugin features, settings, and usage, and diagnose plugin errors by reading the user's debug.log (when File Logging is enabled). Activate this skill whenever the user asks how to use the plugin or configure settings, OR reports that something went wrong with the plugin — bug, error, crash, broken behavior, "not working", "what just happened" — especially when they mention the debug log, log file, console output, or want help troubleshooting. Always activate this skill before searching the vault for plugin log files; debug.log lives in the plugin state folder which the standard read_file tool blocks.
 ---
 
 # Gemini Scribe Help
@@ -24,3 +24,14 @@ User asks: "How do I set up inline completions?"
 
 1. Load `references/completions.md` via `activate_skill(name: "gemini-scribe-help", resource_path: "references/completions.md")`
 2. Answer using the loaded content
+
+## Troubleshooting with Debug Logs
+
+When a user reports a bug or unexpected behavior, check whether they have **Log to File** enabled (Settings → Developer → Log to File). When enabled, two additional resources are available on this skill:
+
+- `debug.log` — current log file
+- `debug.log.old` — previous rotated log (present only after a rotation)
+
+Load them the same way as a reference, e.g. `activate_skill(name: "gemini-scribe-help", resource_path: "debug.log")`. Each entry is timestamped with a severity level (`LOG`, `DEBUG`, `ERROR`, `WARN`); focus on `ERROR` and `WARN` entries near the time the user encountered the issue.
+
+If `activate_skill` returns "Resource not found" for these paths, Log to File may be disabled, or the log file may not exist yet (e.g. `debug.log.old` is only present after a rotation). Ask the user to enable Log to File (and Debug Mode for verbose entries), reproduce the issue once, then re-check.

src/services/skill-manager.ts

@@ -34,6 +34,20 @@ const SKILL_NAME_REGEX = /^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$/;
 const SKILL_NAME_MAX_LENGTH = 64;
 const SKILL_MD_FILENAME = 'SKILL.md';
 
+/**
+ * The bundled help skill exposes the plugin's debug log files as virtual
+ * resources when file logging is enabled, so the agent can self-diagnose
+ * user-reported issues. These files live in the plugin state folder, which
+ * the standard read_file tool blocks.
+ */
+const HELP_SKILL_NAME = 'gemini-scribe-help';
+const HELP_DEBUG_LOG_RESOURCES = ['debug.log', 'debug.log.old'] as const;
+type HelpDebugLogResource = (typeof HELP_DEBUG_LOG_RESOURCES)[number];
+
+function isHelpDebugLogResource(path: string): path is HelpDebugLogResource {
+	return (HELP_DEBUG_LOG_RESOURCES as readonly string[]).includes(path);
+}
+
 /**
  * Find the character offset of the closing YAML frontmatter delimiter in a file's content.
  * Returns the offset immediately AFTER the closing delimiter token (`---` or `...`)
@@ -220,6 +234,11 @@ export class SkillManager {
 			return null;
 		}
 
+		// Help skill exposes debug.log / debug.log.old as virtual resources.
+		if (skillName === HELP_SKILL_NAME && isHelpDebugLogResource(relativePath)) {
+			return await this.readHelpDebugLog(relativePath);
+		}
+
 		const resourcePath = normalizePath(`${this.getSkillsFolderPath()}/${skillName}/${relativePath}`);
 
 		// Verify resolved path stays within the skill directory
@@ -238,6 +257,24 @@ export class SkillManager {
 		return await this.plugin.app.vault.read(file);
 	}
 
+	/**
+	 * Read a debug log file from the plugin state folder for the help skill.
+	 * Returns null when file logging is disabled or the log file is absent.
+	 */
+	private async readHelpDebugLog(filename: HelpDebugLogResource): Promise<string | null> {
+		if (!this.plugin.settings?.fileLogging) return null;
+		const adapter = this.plugin.app?.vault?.adapter;
+		if (!adapter) return null;
+		const path = normalizePath(`${this.plugin.settings.historyFolder}/${filename}`);
+		try {
+			if (!(await adapter.exists(path))) return null;
+			return await adapter.read(path);
+		} catch (error) {
+			this.plugin.logger.warn(`Failed to read debug log "${path}":`, error);
+			return null;
+		}
+	}
+
 	/**
 	 * List available resources within a skill directory
 	 */
@@ -251,16 +288,43 @@ export class SkillManager {
 		const skillDir = normalizePath(`${this.getSkillsFolderPath()}/${skillName}`);
 		const folder = this.plugin.app.vault.getAbstractFileByPath(skillDir);
 
-		if (!(folder instanceof TFolder)) {
+		let resources: string[];
+		if (folder instanceof TFolder) {
+			resources = [];
+			this.collectFiles(folder, skillDir, resources);
+		} else {
 			// Fall back to bundled skill resources
-			return BundledSkillRegistry.listResources(skillName);
+			resources = [...BundledSkillRegistry.listResources(skillName)];
+		}
+
+		// Help skill exposes debug.log / debug.log.old as virtual resources
+		// when the user has file logging enabled and a log file exists.
+		if (skillName === HELP_SKILL_NAME) {
+			const debugLogs = await this.listHelpDebugLogResources();
+			for (const name of debugLogs) {
+				if (!resources.includes(name)) resources.push(name);
+			}
 		}
 
-		const resources: string[] = [];
-		this.collectFiles(folder, skillDir, resources);
 		return resources;
 	}
 
+	private async listHelpDebugLogResources(): Promise<HelpDebugLogResource[]> {
+		if (!this.plugin.settings?.fileLogging) return [];
+		const adapter = this.plugin.app?.vault?.adapter;
+		if (!adapter) return [];
+		const present: HelpDebugLogResource[] = [];
+		for (const name of HELP_DEBUG_LOG_RESOURCES) {
+			const path = normalizePath(`${this.plugin.settings.historyFolder}/${name}`);
+			try {
+				if (await adapter.exists(path)) present.push(name);
+			} catch {
+				// Treat probe failures as "not present"; never throw from listing.
+			}
+		}
+		return present;
+	}
+
 	/**
 	 * Recursively collect file paths relative to a base directory
 	 */

test/services/skill-manager.test.ts

@@ -71,7 +71,10 @@ const mockVault = {
 	create: jest.fn(),
 	read: jest.fn(),
 	getMarkdownFiles: jest.fn(),
-	adapter: { exists: jest.fn().mockResolvedValue(false) },
+	adapter: {
+		exists: jest.fn().mockResolvedValue(false),
+		read: jest.fn().mockResolvedValue(''),
+	},
 };
 
 const mockMetadataCache = {
@@ -104,6 +107,11 @@ describe('SkillManager', () => {
 
 	beforeEach(() => {
 		jest.clearAllMocks();
+		// clearAllMocks resets call history but keeps any custom implementations
+		// from prior tests, so re-pin adapter defaults explicitly.
+		mockVault.adapter.exists.mockReset().mockResolvedValue(false);
+		mockVault.adapter.read.mockReset().mockResolvedValue('');
+		mockPlugin.settings.fileLogging = false;
 		manager = new SkillManager(mockPlugin);
 	});
 
@@ -266,6 +274,128 @@ describe('SkillManager', () => {
 			const content = await manager.readSkillResource('my-skill', '/etc/passwd');
 			expect(content).toBeNull();
 		});
+
+		describe('help skill debug log virtual resources', () => {
+			beforeEach(() => {
+				// readHelpDebugLog goes through vault.adapter, not getAbstractFileByPath.
+				mockVault.getAbstractFileByPath.mockReturnValue(null);
+			});
+
+			it('should read debug.log via the help skill when fileLogging is on', async () => {
+				mockPlugin.settings.fileLogging = true;
+				mockVault.adapter.exists.mockImplementation(async (path: string) => path === 'gemini-scribe/debug.log');
+				mockVault.adapter.read.mockResolvedValue('[2026-04-25T10:00:00] [ERROR] [Gemini Scribe] boom');
+
+				const content = await manager.readSkillResource('gemini-scribe-help', 'debug.log');
+
+				expect(content).toBe('[2026-04-25T10:00:00] [ERROR] [Gemini Scribe] boom');
+				expect(mockVault.adapter.read).toHaveBeenCalledWith('gemini-scribe/debug.log');
+			});
+
+			it('should read debug.log.old when present', async () => {
+				mockPlugin.settings.fileLogging = true;
+				mockVault.adapter.exists.mockImplementation(async (path: string) => path === 'gemini-scribe/debug.log.old');
+				mockVault.adapter.read.mockResolvedValue('rotated content');
+
+				const content = await manager.readSkillResource('gemini-scribe-help', 'debug.log.old');
+
+				expect(content).toBe('rotated content');
+				expect(mockVault.adapter.read).toHaveBeenCalledWith('gemini-scribe/debug.log.old');
+			});
+
+			it('should return null when fileLogging is disabled', async () => {
+				mockPlugin.settings.fileLogging = false;
+				mockVault.adapter.exists.mockResolvedValue(true);
+
+				const content = await manager.readSkillResource('gemini-scribe-help', 'debug.log');
+
+				expect(content).toBeNull();
+				// Must not even probe disk when the user has opted out.
+				expect(mockVault.adapter.exists).not.toHaveBeenCalled();
+				expect(mockVault.adapter.read).not.toHaveBeenCalled();
+			});
+
+			it('should return null when log file does not exist', async () => {
+				mockPlugin.settings.fileLogging = true;
+				mockVault.adapter.exists.mockResolvedValue(false);
+
+				const content = await manager.readSkillResource('gemini-scribe-help', 'debug.log');
+
+				expect(content).toBeNull();
+				expect(mockVault.adapter.read).not.toHaveBeenCalled();
+			});
+
+			it('should not expose debug.log on other skills', async () => {
+				mockPlugin.settings.fileLogging = true;
+				mockVault.adapter.exists.mockResolvedValue(true);
+				mockVault.adapter.read.mockResolvedValue('should not be returned');
+
+				const content = await manager.readSkillResource('gemini-scribe', 'debug.log');
+
+				expect(content).toBeNull();
+				expect(mockVault.adapter.read).not.toHaveBeenCalled();
+			});
+
+			it('should still reject path traversal even for the help skill', async () => {
+				mockPlugin.settings.fileLogging = true;
+				const content = await manager.readSkillResource('gemini-scribe-help', '../debug.log');
+				expect(content).toBeNull();
+			});
+		});
+	});
+
+	describe('listSkillResources', () => {
+		beforeEach(() => {
+			// Default: no vault skill dir, no debug log files.
+			mockVault.getAbstractFileByPath.mockReturnValue(null);
+			mockVault.adapter.exists.mockResolvedValue(false);
+		});
+
+		it('should fall through to bundled resources when no vault folder', async () => {
+			const resources = await manager.listSkillResources('gemini-scribe-help');
+			expect(resources).toEqual(expect.arrayContaining(['references/agent-mode.md', 'references/settings.md']));
+		});
+
+		it('should append debug.log resources for the help skill when fileLogging is on and files exist', async () => {
+			mockPlugin.settings.fileLogging = true;
+			mockVault.adapter.exists.mockImplementation(
+				async (path: string) => path === 'gemini-scribe/debug.log' || path === 'gemini-scribe/debug.log.old'
+			);
+
+			const resources = await manager.listSkillResources('gemini-scribe-help');
+
+			expect(resources).toEqual(expect.arrayContaining(['debug.log', 'debug.log.old']));
+		});
+
+		it('should only include logs that exist on disk', async () => {
+			mockPlugin.settings.fileLogging = true;
+			mockVault.adapter.exists.mockImplementation(async (path: string) => path === 'gemini-scribe/debug.log');
+
+			const resources = await manager.listSkillResources('gemini-scribe-help');
+
+			expect(resources).toContain('debug.log');
+			expect(resources).not.toContain('debug.log.old');
+		});
+
+		it('should omit debug logs when fileLogging is disabled', async () => {
+			mockPlugin.settings.fileLogging = false;
+			mockVault.adapter.exists.mockResolvedValue(true);
+
+			const resources = await manager.listSkillResources('gemini-scribe-help');
+
+			expect(resources).not.toContain('debug.log');
+			expect(resources).not.toContain('debug.log.old');
+		});
+
+		it('should not add debug logs to other skills', async () => {
+			mockPlugin.settings.fileLogging = true;
+			mockVault.adapter.exists.mockResolvedValue(true);
+
+			const resources = await manager.listSkillResources('obsidian-bases');
+
+			expect(resources).not.toContain('debug.log');
+			expect(resources).not.toContain('debug.log.old');
+		});
 	});
 
 	describe('getSkillSummaries', () => {