btca-server 1.0.40 → 1.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "btca-server",
-	"version": "1.0.40",
+	"version": "1.0.43",
 	"description": "BTCA server for answering questions about your codebase using OpenCode AI",
 	"author": "Ben Davis",
 	"license": "MIT",

package/src/agent/service.ts

@@ -89,9 +89,15 @@ export namespace Agent {
 			url: string;
 			model: { provider: string; model: string };
 		}>;
+
+		listProviders: () => Promise<{ all: { id: string; models: Record<string, unknown> }[]; connected: string[] }>;
 	};
 
-	const buildOpenCodeConfig = (args: { agentInstructions: string }): OpenCodeConfig => {
+	const buildOpenCodeConfig = (args: {
+		agentInstructions: string;
+		providerId?: string;
+		providerTimeoutMs?: number;
+	}): OpenCodeConfig => {
 		const prompt = [
 			'You are an expert internal agent whose job is to answer questions about the collection.',
 			'You operate inside a collection directory.',
@@ -99,6 +105,17 @@ export namespace Agent {
 			args.agentInstructions
 		].join('\n');
 
+		const providerConfig =
+			args.providerId && typeof args.providerTimeoutMs === 'number'
+				? {
+						[args.providerId]: {
+							options: {
+								timeout: args.providerTimeoutMs
+							}
+						}
+					}
+				: undefined;
+
 		return {
 			agent: {
 				build: { disable: true },
@@ -135,7 +152,8 @@ export namespace Agent {
 						edit: false
 					}
 				}
-			}
+			},
+			...(providerConfig ? { provider: providerConfig } : {})
 		};
 	};
 
@@ -164,7 +182,7 @@ export namespace Agent {
 		}
 	};
 
-	const getOpencodeInstance = async (args: {
+	const createOpencodeInstance = async (args: {
 		collectionPath: string;
 		ocConfig: OpenCodeConfig;
 	}): Promise<{
@@ -248,8 +266,12 @@ export namespace Agent {
 
 	export const create = (config: Config.Service): Service => {
 		const askStream: Service['askStream'] = async ({ collection, question }) => {
-			const ocConfig = buildOpenCodeConfig({ agentInstructions: collection.agentInstructions });
-			const { client, server, baseUrl } = await getOpencodeInstance({
+			const ocConfig = buildOpenCodeConfig({
+				agentInstructions: collection.agentInstructions,
+				providerId: config.provider,
+				providerTimeoutMs: config.providerTimeoutMs
+			});
+			const { client, server, baseUrl } = await createOpencodeInstance({
 				collectionPath: collection.path,
 				ocConfig
 			});
@@ -354,8 +376,12 @@ export namespace Agent {
 		};
 
 		const getOpencodeInstanceMethod: Service['getOpencodeInstance'] = async ({ collection }) => {
-			const ocConfig = buildOpenCodeConfig({ agentInstructions: collection.agentInstructions });
-			const { baseUrl } = await getOpencodeInstance({
+			const ocConfig = buildOpenCodeConfig({
+				agentInstructions: collection.agentInstructions,
+				providerId: config.provider,
+				providerTimeoutMs: config.providerTimeoutMs
+			});
+			const { baseUrl } = await createOpencodeInstance({
 				collectionPath: collection.path,
 				ocConfig
 			});
@@ -371,6 +397,41 @@ export namespace Agent {
 			};
 		};
 
-		return { askStream, ask, getOpencodeInstance: getOpencodeInstanceMethod };
+		const listProviders: Service['listProviders'] = async () => {
+			const ocConfig = buildOpenCodeConfig({
+				agentInstructions: '',
+				providerId: config.provider,
+				providerTimeoutMs: config.providerTimeoutMs
+			});
+			const { client, server } = await createOpencodeInstance({
+				collectionPath: process.cwd(),
+				ocConfig
+			});
+
+			try {
+				const response = await client.provider.list().catch((cause: unknown) => {
+					throw new AgentError({
+						message: 'Failed to fetch provider list',
+						hint: CommonHints.RUN_AUTH,
+						cause
+					});
+				});
+				if (!response?.data) {
+					throw new AgentError({
+						message: 'Failed to fetch provider list',
+						hint: CommonHints.RUN_AUTH
+					});
+				}
+				const data = response.data as {
+					all: { id: string; models: Record<string, unknown> }[];
+					connected: string[];
+				};
+				return { all: data.all, connected: data.connected };
+			} finally {
+				server.close();
+			}
+		};
+
+		return { askStream, ask, getOpencodeInstance: getOpencodeInstanceMethod, listProviders };
 	};
 }

package/src/collections/service.ts

@@ -18,11 +18,14 @@ export namespace Collections {
 	};
 
 	const createCollectionInstructionBlock = (resource: BtcaFsResource): string => {
+		const focusLines = resource.repoSubPaths.map(
+			(subPath) => `Focus: ./${resource.fsName}/${subPath}`
+		);
 		const lines = [
 			`## Resource: ${resource.name}`,
 			FS_RESOURCE_SYSTEM_NOTE,
-			`Path: ./${resource.name}`,
-			resource.repoSubPath ? `Focus: ./${resource.name}/${resource.repoSubPath}` : '',
+			`Path: ./${resource.fsName}`,
+			...focusLines,
 			resource.specialAgentInstructions ? `Notes: ${resource.specialAgentInstructions}` : ''
 		].filter(Boolean);
 
@@ -89,7 +92,7 @@ export namespace Collections {
 							});
 						}
 
-						const linkPath = path.join(collectionPath, resource.name);
+						const linkPath = path.join(collectionPath, resource.fsName);
 						try {
 							await fs.rm(linkPath, { recursive: true, force: true });
 						} catch {
@@ -97,7 +100,7 @@ export namespace Collections {
 						}
 
 						try {
-							await fs.symlink(resourcePath, linkPath);
+							await fs.symlink(resourcePath, linkPath, 'junction');
 						} catch (cause) {
 							throw new CollectionError({
 								message: `Failed to create symlink for resource "${resource.name}"`,

package/src/collections/types.ts

@@ -1,4 +1,5 @@
 import type { TaggedErrorOptions } from '../errors.ts';
+import { resourceNameToKey } from '../resources/helpers.ts';
 
 export type CollectionResult = {
 	path: string;
@@ -18,5 +19,5 @@ export class CollectionError extends Error {
 }
 
 export const getCollectionKey = (resourceNames: readonly string[]): string => {
-	return [...resourceNames].sort().join('+');
+	return [...resourceNames].map(resourceNameToKey).sort().join('+');
 };

package/src/config/index.ts

@@ -1,4 +1,5 @@
 import { promises as fs } from 'node:fs';
+import path from 'node:path';
 
 import { z } from 'zod';
 import { CommonHints, type TaggedErrorOptions } from '../errors.ts';
@@ -10,11 +11,11 @@ export const GLOBAL_CONFIG_FILENAME = 'btca.config.jsonc';
 export const LEGACY_CONFIG_FILENAME = 'btca.json';
 export const GLOBAL_DATA_DIR = '~/.local/share/btca';
 export const PROJECT_CONFIG_FILENAME = 'btca.config.jsonc';
-export const PROJECT_DATA_DIR = '.btca';
 export const CONFIG_SCHEMA_URL = 'https://btca.dev/btca.schema.json';
 
 export const DEFAULT_MODEL = 'claude-haiku-4-5';
 export const DEFAULT_PROVIDER = 'opencode';
+export const DEFAULT_PROVIDER_TIMEOUT_MS = 300_000;
 
 export const DEFAULT_RESOURCES: ResourceDefinition[] = [
 	{
@@ -48,6 +49,8 @@ export const DEFAULT_RESOURCES: ResourceDefinition[] = [
 
 const StoredConfigSchema = z.object({
 	$schema: z.string().optional(),
+	dataDirectory: z.string().optional(),
+	providerTimeoutMs: z.number().int().positive().optional(),
 	resources: z.array(ResourceDefinitionSchema),
 	model: z.string(),
 	provider: z.string()
@@ -113,6 +116,7 @@ export namespace Config {
 		resources: readonly ResourceDefinition[];
 		model: string;
 		provider: string;
+		providerTimeoutMs?: number;
 		configPath: string;
 		getResource: (name: string) => ResourceDefinition | undefined;
 		updateModel: (provider: string, model: string) => Promise<{ provider: string; model: string }>;
@@ -127,6 +131,12 @@ export namespace Config {
 		return path;
 	};
 
+	const resolveDataDirectory = (rawPath: string, baseDir: string): string => {
+		const expanded = expandHome(rawPath);
+		if (path.isAbsolute(expanded)) return expanded;
+		return path.resolve(baseDir, expanded);
+	};
+
 	const stripJsonc = (content: string): string => {
 		// Remove // and /* */ comments without touching strings.
 		let out = '';
@@ -427,7 +437,8 @@ export namespace Config {
 			$schema: CONFIG_SCHEMA_URL,
 			resources: DEFAULT_RESOURCES,
 			model: DEFAULT_MODEL,
-			provider: DEFAULT_PROVIDER
+			provider: DEFAULT_PROVIDER,
+			providerTimeoutMs: DEFAULT_PROVIDER_TIMEOUT_MS
 		};
 
 		try {
@@ -526,6 +537,9 @@ export namespace Config {
 			get provider() {
 				return getActiveConfig().provider;
 			},
+			get providerTimeoutMs() {
+				return getActiveConfig().providerTimeoutMs;
+			},
 			getResource: (name: string) => getMergedResources().find((r) => r.name === name),
 
 			updateModel: async (provider: string, model: string) => {
@@ -680,7 +694,7 @@ export namespace Config {
 		const projectExists = await Bun.file(projectConfigPath).exists();
 		if (projectExists) {
 			Metrics.info('config.load.project', { source: 'project', path: projectConfigPath });
-			const projectConfig = await loadConfigFromPath(projectConfigPath);
+			let projectConfig = await loadConfigFromPath(projectConfigPath);
 
 			Metrics.info('config.load.merged', {
 				globalResources: globalConfig.resources.length,
@@ -689,22 +703,50 @@ export namespace Config {
 
 			// Use project paths for data storage when project config exists
 			// Pass both configs separately to avoid resource leakage on mutations
+			let projectDataDir =
+				projectConfig.dataDirectory ?? globalConfig.dataDirectory ?? expandHome(GLOBAL_DATA_DIR);
+
+			// Migration: if no dataDirectory is set and legacy .btca exists, use it and update config
+			if (!projectConfig.dataDirectory) {
+				const legacyProjectDataDir = `${cwd}/.btca`;
+				const legacyExists = await fs
+					.stat(legacyProjectDataDir)
+					.then(() => true)
+					.catch(() => false);
+				if (legacyExists) {
+					Metrics.info('config.project.legacy_data_dir', {
+						path: legacyProjectDataDir,
+						action: 'migrating'
+					});
+					projectDataDir = '.btca';
+					const updatedProjectConfig = { ...projectConfig, dataDirectory: '.btca' };
+					await saveConfig(projectConfigPath, updatedProjectConfig);
+					projectConfig = updatedProjectConfig;
+				}
+			}
+
+			const resolvedProjectDataDir = resolveDataDirectory(projectDataDir, cwd);
 			return makeService(
 				globalConfig,
 				projectConfig,
-				`${cwd}/${PROJECT_DATA_DIR}/resources`,
-				`${cwd}/${PROJECT_DATA_DIR}/collections`,
+				`${resolvedProjectDataDir}/resources`,
+				`${resolvedProjectDataDir}/collections`,
 				projectConfigPath
 			);
 		}
 
 		// No project config, use global only
 		Metrics.info('config.load.source', { source: 'global', path: globalConfigPath });
+		const globalDataDir = globalConfig.dataDirectory ?? expandHome(GLOBAL_DATA_DIR);
+		const resolvedGlobalDataDir = resolveDataDirectory(
+			globalDataDir,
+			expandHome(GLOBAL_CONFIG_DIR)
+		);
 		return makeService(
 			globalConfig,
 			null,
-			`${expandHome(GLOBAL_DATA_DIR)}/resources`,
-			`${expandHome(GLOBAL_DATA_DIR)}/collections`,
+			`${resolvedGlobalDataDir}/resources`,
+			`${resolvedGlobalDataDir}/collections`,
 			globalConfigPath
 		);
 	};

package/src/index.ts

@@ -13,7 +13,7 @@ import { Resources } from './resources/service.ts';
 import { GitResourceSchema, LocalResourceSchema } from './resources/schema.ts';
 import { StreamService } from './stream/service.ts';
 import type { BtcaStreamMetaEvent } from './stream/types.ts';
-import { LIMITS } from './validation/index.ts';
+import { LIMITS, normalizeGitHubUrl } from './validation/index.ts';
 
 /**
  * BTCA Server API
@@ -42,7 +42,7 @@ const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : DEFAULT_PORT;
 /**
  * Resource name pattern: must start with a letter, alphanumeric and hyphens only.
  */
-const RESOURCE_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+const RESOURCE_NAME_REGEX = /^@?[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
 
 /**
  * Safe name pattern for provider/model names.
@@ -56,7 +56,10 @@ const ResourceNameField = z
 	.string()
 	.min(1, 'Resource name cannot be empty')
 	.max(LIMITS.RESOURCE_NAME_MAX)
-	.regex(RESOURCE_NAME_REGEX, 'Invalid resource name format');
+	.regex(RESOURCE_NAME_REGEX, 'Invalid resource name format')
+	.refine((name) => !name.includes('..'), 'Resource name must not contain ".."')
+	.refine((name) => !name.includes('//'), 'Resource name must not contain "//"')
+	.refine((name) => !name.endsWith('/'), 'Resource name must not end with "/"');
 
 const QuestionRequestSchema = z.object({
 	question: z
@@ -110,6 +113,7 @@ const AddGitResourceRequestSchema = z.object({
 	url: GitResourceSchema.shape.url,
 	branch: GitResourceSchema.shape.branch.optional().default('main'),
 	searchPath: GitResourceSchema.shape.searchPath,
+	searchPaths: GitResourceSchema.shape.searchPaths,
 	specialNotes: GitResourceSchema.shape.specialNotes
 });
 
@@ -220,6 +224,7 @@ const createApp = (deps: {
 			return c.json({
 				provider: config.provider,
 				model: config.model,
+				providerTimeoutMs: config.providerTimeoutMs ?? null,
 				resourcesDirectory: config.resourcesDirectory,
 				collectionsDirectory: config.collectionsDirectory,
 				resourceCount: config.resources.length
@@ -237,6 +242,7 @@ const createApp = (deps: {
 							url: r.url,
 							branch: r.branch,
 							searchPath: r.searchPath ?? null,
+							searchPaths: r.searchPaths ?? null,
 							specialNotes: r.specialNotes ?? null
 						};
 					} else {
@@ -251,6 +257,12 @@ const createApp = (deps: {
 			});
 		})
 
+		// GET /providers
+		.get('/providers', async (c: HonoContext) => {
+			const providers = await agent.listProviders();
+			return c.json(providers);
+		})
+
 		// POST /question
 		.post('/question', async (c: HonoContext) => {
 			const decoded = await decodeJson(c.req.raw, QuestionRequestSchema);
@@ -375,16 +387,20 @@ const createApp = (deps: {
 
 		// POST /config/resources - Add a new resource
 		// All validation (URL, branch, path traversal, etc.) is handled by the schema
+		// GitHub URLs are normalized to their base repository format
 		.post('/config/resources', async (c: HonoContext) => {
 			const decoded = await decodeJson(c.req.raw, AddResourceRequestSchema);
 
 			if (decoded.type === 'git') {
+				// Normalize GitHub URLs (e.g., /blob/main/file.txt → base repo URL)
+				const normalizedUrl = normalizeGitHubUrl(decoded.url);
 				const resource = {
 					type: 'git' as const,
 					name: decoded.name,
-					url: decoded.url,
+					url: normalizedUrl,
 					branch: decoded.branch ?? 'main',
 					...(decoded.searchPath && { searchPath: decoded.searchPath }),
+					...(decoded.searchPaths && { searchPaths: decoded.searchPaths }),
 					...(decoded.specialNotes && { specialNotes: decoded.specialNotes })
 				};
 				const added = await config.addResource(resource);
@@ -468,7 +484,8 @@ export const startServer = async (options: StartServerOptions = {}): Promise<Ser
 
 	const server = Bun.serve({
 		port: requestedPort,
-		fetch: app.fetch
+		fetch: app.fetch,
+		idleTimeout: 60
 	});
 
 	const actualPort = server.port ?? requestedPort;

package/src/resources/helpers.ts

@@ -12,3 +12,7 @@ export class ResourceError extends Error {
 		if (args.stack) this.stack = args.stack;
 	}
 }
+
+export const resourceNameToKey = (name: string): string => {
+	return encodeURIComponent(name);
+};

package/src/resources/impls/git.test.ts

@@ -25,7 +25,7 @@ describe('Git Resource', () => {
 					name: 'test-repo',
 					url: 'https://github.com/honojs/hono',
 					branch: 'main',
-					repoSubPath: 'docs',
+					repoSubPaths: ['docs'],
 					resourcesDirectoryPath: testDir,
 					specialAgentInstructions: 'Test notes',
 					quiet: true
@@ -36,7 +36,7 @@ describe('Git Resource', () => {
 				expect(resource._tag).toBe('fs-based');
 				expect(resource.name).toBe('test-repo');
 				expect(resource.type).toBe('git');
-				expect(resource.repoSubPath).toBe('docs');
+				expect(resource.repoSubPaths).toEqual(['docs']);
 				expect(resource.specialAgentInstructions).toBe('Test notes');
 
 				const resourcePath = await resource.getAbsoluteDirectoryPath();
@@ -55,7 +55,7 @@ describe('Git Resource', () => {
 					name: 'update-test',
 					url: 'https://github.com/honojs/hono',
 					branch: 'main',
-					repoSubPath: '',
+					repoSubPaths: [],
 					resourcesDirectoryPath: testDir,
 					specialAgentInstructions: '',
 					quiet: true
@@ -77,13 +77,13 @@ describe('Git Resource', () => {
 				name: 'invalid-url',
 				url: 'not-a-valid-url',
 				branch: 'main',
-				repoSubPath: '',
+				repoSubPaths: [],
 				resourcesDirectoryPath: testDir,
 				specialAgentInstructions: '',
 				quiet: true
 			};
 
-			expect(loadGitResource(args)).rejects.toThrow('Invalid git URL');
+			expect(loadGitResource(args)).rejects.toThrow('Git URL must be a valid HTTPS URL');
 		});
 
 		it('throws error for invalid branch name', async () => {
@@ -92,13 +92,13 @@ describe('Git Resource', () => {
 				name: 'invalid-branch',
 				url: 'https://github.com/test/repo',
 				branch: 'invalid branch name!',
-				repoSubPath: '',
+				repoSubPaths: [],
 				resourcesDirectoryPath: testDir,
 				specialAgentInstructions: '',
 				quiet: true
 			};
 
-			expect(loadGitResource(args)).rejects.toThrow('Invalid branch name');
+			expect(loadGitResource(args)).rejects.toThrow('Branch name must contain only');
 		});
 
 		it('throws error for path traversal attempt', async () => {
@@ -107,13 +107,13 @@ describe('Git Resource', () => {
 				name: 'path-traversal',
 				url: 'https://github.com/test/repo',
 				branch: 'main',
-				repoSubPath: '../../../etc',
+				repoSubPaths: ['../../../etc'],
 				resourcesDirectoryPath: testDir,
 				specialAgentInstructions: '',
 				quiet: true
 			};
 
-			expect(loadGitResource(args)).rejects.toThrow('Invalid search path');
+			expect(loadGitResource(args)).rejects.toThrow('path traversal');
 		});
 	});
 });

package/src/resources/impls/git.ts

@@ -1,13 +1,31 @@
 import { promises as fs } from 'node:fs';
+import path from 'node:path';
 
 import { Metrics } from '../../metrics/index.ts';
 import { CommonHints } from '../../errors.ts';
-import { ResourceError } from '../helpers.ts';
+import { ResourceError, resourceNameToKey } from '../helpers.ts';
+import { GitResourceSchema } from '../schema.ts';
 import type { BtcaFsResource, BtcaGitResourceArgs } from '../types.ts';
 
-const isValidGitUrl = (url: string) => /^https:\/\//.test(url);
-const isValidBranch = (branch: string) => /^[\w\-./]+$/.test(branch);
-const isValidPath = (path: string) => !path.includes('..') && /^[\w\-./]*$/.test(path);
+const validateGitUrl = (url: string): { success: true } | { success: false; error: string } => {
+	const result = GitResourceSchema.shape.url.safeParse(url);
+	if (result.success) return { success: true };
+	return { success: false, error: result.error.errors[0]?.message ?? 'Invalid git URL' };
+};
+
+const validateBranch = (branch: string): { success: true } | { success: false; error: string } => {
+	const result = GitResourceSchema.shape.branch.safeParse(branch);
+	if (result.success) return { success: true };
+	return { success: false, error: result.error.errors[0]?.message ?? 'Invalid branch name' };
+};
+
+const validateSearchPath = (
+	searchPath: string
+): { success: true } | { success: false; error: string } => {
+	const result = GitResourceSchema.shape.searchPath.safeParse(searchPath);
+	if (result.success) return { success: true };
+	return { success: false, error: result.error.errors[0]?.message ?? 'Invalid search path' };
+};
 
 const directoryExists = async (path: string): Promise<boolean> => {
 	try {
@@ -173,33 +191,38 @@ const runGit = async (
 const gitClone = async (args: {
 	repoUrl: string;
 	repoBranch: string;
-	repoSubPath: string;
+	repoSubPaths: readonly string[];
 	localAbsolutePath: string;
 	quiet: boolean;
 }) => {
-	if (!isValidGitUrl(args.repoUrl)) {
+	const urlValidation = validateGitUrl(args.repoUrl);
+	if (!urlValidation.success) {
 		throw new ResourceError({
-			message: 'Invalid git URL format',
-			hint: 'URLs must start with "https://". Example: https://github.com/user/repo',
+			message: urlValidation.error,
+			hint: 'URLs must be valid HTTPS URLs. Example: https://github.com/user/repo',
 			cause: new Error('URL validation failed')
 		});
 	}
-	if (!isValidBranch(args.repoBranch)) {
+	const branchValidation = validateBranch(args.repoBranch);
+	if (!branchValidation.success) {
 		throw new ResourceError({
-			message: `Invalid branch name: "${args.repoBranch}"`,
+			message: branchValidation.error,
 			hint: 'Branch names can only contain letters, numbers, hyphens, underscores, dots, and forward slashes.',
 			cause: new Error('Branch validation failed')
 		});
 	}
-	if (args.repoSubPath && !isValidPath(args.repoSubPath)) {
-		throw new ResourceError({
-			message: `Invalid search path: "${args.repoSubPath}"`,
-			hint: 'Search paths cannot contain ".." (path traversal) and must use only safe characters.',
-			cause: new Error('Path validation failed')
-		});
+	for (const repoSubPath of args.repoSubPaths) {
+		const pathValidation = validateSearchPath(repoSubPath);
+		if (!pathValidation.success) {
+			throw new ResourceError({
+				message: pathValidation.error,
+				hint: 'Search paths cannot contain ".." (path traversal) and must use only safe characters.',
+				cause: new Error('Path validation failed')
+			});
+		}
 	}
 
-	const needsSparseCheckout = args.repoSubPath && args.repoSubPath !== '/';
+	const needsSparseCheckout = args.repoSubPaths.length > 0;
 	const cloneArgs = needsSparseCheckout
 		? [
 				'clone',
@@ -231,15 +254,15 @@ const gitClone = async (args: {
 	}
 
 	if (needsSparseCheckout) {
-		const sparseResult = await runGit(['sparse-checkout', 'set', args.repoSubPath], {
+		const sparseResult = await runGit(['sparse-checkout', 'set', ...args.repoSubPaths], {
 			cwd: args.localAbsolutePath,
 			quiet: args.quiet
 		});
 
 		if (sparseResult.exitCode !== 0) {
 			throw new ResourceError({
-				message: `Failed to set sparse-checkout path: "${args.repoSubPath}"`,
-				hint: 'Verify the search path exists in the repository. Check the repository structure to find the correct path.',
+				message: `Failed to set sparse-checkout path(s): "${args.repoSubPaths.join(', ')}"`,
+				hint: 'Verify the search paths exist in the repository. Check the repository structure to find the correct path.',
 				cause: new Error(
 					`git sparse-checkout failed with exit code ${sparseResult.exitCode}: ${sparseResult.stderr}`
 				)
@@ -263,7 +286,12 @@ const gitClone = async (args: {
 	}
 };
 
-const gitUpdate = async (args: { localAbsolutePath: string; branch: string; quiet: boolean }) => {
+const gitUpdate = async (args: {
+	localAbsolutePath: string;
+	branch: string;
+	repoSubPaths: readonly string[];
+	quiet: boolean;
+}) => {
 	const fetchResult = await runGit(['fetch', '--depth', '1', 'origin', args.branch], {
 		cwd: args.localAbsolutePath,
 		quiet: args.quiet
@@ -299,10 +327,60 @@ const gitUpdate = async (args: { localAbsolutePath: string; branch: string; quie
 			)
 		});
 	}
+
+	if (args.repoSubPaths.length > 0) {
+		const sparseResult = await runGit(['sparse-checkout', 'set', ...args.repoSubPaths], {
+			cwd: args.localAbsolutePath,
+			quiet: args.quiet
+		});
+
+		if (sparseResult.exitCode !== 0) {
+			throw new ResourceError({
+				message: `Failed to set sparse-checkout path(s): "${args.repoSubPaths.join(', ')}"`,
+				hint: 'Verify the search paths exist in the repository. Check the repository structure to find the correct path.',
+				cause: new Error(
+					`git sparse-checkout failed with exit code ${sparseResult.exitCode}: ${sparseResult.stderr}`
+				)
+			});
+		}
+
+		const checkoutResult = await runGit(['checkout'], {
+			cwd: args.localAbsolutePath,
+			quiet: args.quiet
+		});
+
+		if (checkoutResult.exitCode !== 0) {
+			throw new ResourceError({
+				message: 'Failed to checkout repository',
+				hint: CommonHints.CLEAR_CACHE,
+				cause: new Error(
+					`git checkout failed with exit code ${checkoutResult.exitCode}: ${checkoutResult.stderr}`
+				)
+			});
+		}
+	}
+};
+
+const ensureSearchPathsExist = async (
+	localPath: string,
+	repoSubPaths: readonly string[]
+): Promise<void> => {
+	for (const repoSubPath of repoSubPaths) {
+		const subPath = path.join(localPath, repoSubPath);
+		const exists = await directoryExists(subPath);
+		if (!exists) {
+			throw new ResourceError({
+				message: `Search path does not exist: "${repoSubPath}"`,
+				hint: 'Check the repository structure and update the search path in your btca config.',
+				cause: new Error(`Missing search path: ${repoSubPath}`)
+			});
+		}
+	}
 };
 
 const ensureGitResource = async (config: BtcaGitResourceArgs): Promise<string> => {
-	const localPath = `${config.resourcesDirectoryPath}/${config.name}`;
+	const resourceKey = resourceNameToKey(config.name);
+	const localPath = path.join(config.resourcesDirectoryPath, resourceKey);
 
 	return Metrics.span(
 		'resource.git.ensure',
@@ -313,20 +391,24 @@ const ensureGitResource = async (config: BtcaGitResourceArgs): Promise<string> =
 				Metrics.info('resource.git.update', {
 					name: config.name,
 					branch: config.branch,
-					repoSubPath: config.repoSubPath
+					repoSubPaths: config.repoSubPaths
 				});
 				await gitUpdate({
 					localAbsolutePath: localPath,
 					branch: config.branch,
+					repoSubPaths: config.repoSubPaths,
 					quiet: config.quiet
 				});
+				if (config.repoSubPaths.length > 0) {
+					await ensureSearchPathsExist(localPath, config.repoSubPaths);
+				}
 				return localPath;
 			}
 
 			Metrics.info('resource.git.clone', {
 				name: config.name,
 				branch: config.branch,
-				repoSubPath: config.repoSubPath
+				repoSubPaths: config.repoSubPaths
 			});
 
 			try {
@@ -342,10 +424,13 @@ const ensureGitResource = async (config: BtcaGitResourceArgs): Promise<string> =
 			await gitClone({
 				repoUrl: config.url,
 				repoBranch: config.branch,
-				repoSubPath: config.repoSubPath,
+				repoSubPaths: config.repoSubPaths,
 				localAbsolutePath: localPath,
 				quiet: config.quiet
 			});
+			if (config.repoSubPaths.length > 0) {
+				await ensureSearchPathsExist(localPath, config.repoSubPaths);
+			}
 
 			return localPath;
 		},
@@ -358,8 +443,9 @@ export const loadGitResource = async (config: BtcaGitResourceArgs): Promise<Btca
 	return {
 		_tag: 'fs-based',
 		name: config.name,
+		fsName: resourceNameToKey(config.name),
 		type: 'git',
-		repoSubPath: config.repoSubPath,
+		repoSubPaths: config.repoSubPaths,
 		specialAgentInstructions: config.specialAgentInstructions,
 		getAbsoluteDirectoryPath: async () => localPath
 	};

package/src/resources/schema.ts

@@ -10,7 +10,7 @@ import { LIMITS } from '../validation/index.ts';
  * Resource name: must start with a letter, followed by alphanumeric and hyphens only.
  * Prevents path traversal, git option injection, and shell metacharacters.
  */
-const RESOURCE_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+const RESOURCE_NAME_REGEX = /^@?[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
 
 /**
  * Branch name: alphanumeric, forward slashes, dots, underscores, and hyphens.
@@ -31,8 +31,17 @@ const ResourceNameSchema = z
 	.max(LIMITS.RESOURCE_NAME_MAX, `Resource name too long (max ${LIMITS.RESOURCE_NAME_MAX} chars)`)
 	.regex(
 		RESOURCE_NAME_REGEX,
-		'Resource name must start with a letter and contain only alphanumeric characters and hyphens'
-	);
+		'Resource name must start with a letter or @ and contain only letters, numbers, ., _, -, and /'
+	)
+	.refine((name) => !name.includes('..'), {
+		message: 'Resource name must not contain ".."'
+	})
+	.refine((name) => !name.includes('//'), {
+		message: 'Resource name must not contain "//"'
+	})
+	.refine((name) => !name.endsWith('/'), {
+		message: 'Resource name must not end with "/"'
+	});
 
 /**
  * Git URL field with security validation.
@@ -113,7 +122,13 @@ const SearchPathSchema = z
 	})
 	.refine((path) => !path.startsWith('/') && !path.match(/^[a-zA-Z]:\\/), {
 		message: 'Search path must not be an absolute path'
-	})
+	});
+
+const OptionalSearchPathSchema = SearchPathSchema.optional();
+
+const SearchPathsSchema = z
+	.array(SearchPathSchema)
+	.refine((paths) => paths.length > 0, { message: 'searchPaths must include at least one path' })
 	.optional();
 
 /**
@@ -151,7 +166,8 @@ export const GitResourceSchema = z.object({
 	name: ResourceNameSchema,
 	url: GitUrlSchema,
 	branch: BranchNameSchema,
-	searchPath: SearchPathSchema,
+	searchPath: OptionalSearchPathSchema,
+	searchPaths: SearchPathsSchema,
 	specialNotes: SpecialNotesSchema
 });
 

package/src/resources/service.ts

@@ -1,6 +1,6 @@
 import { Config } from '../config/index.ts';
 
-import { ResourceError } from './helpers.ts';
+import { ResourceError, resourceNameToKey } from './helpers.ts';
 import { loadGitResource } from './impls/git.ts';
 import {
 	isGitResource,
@@ -20,6 +20,14 @@ export namespace Resources {
 		) => Promise<BtcaFsResource>;
 	};
 
+	const normalizeSearchPaths = (definition: GitResource): string[] => {
+		const paths = [
+			...(definition.searchPaths ?? []),
+			...(definition.searchPath ? [definition.searchPath] : [])
+		];
+		return paths.filter((path) => path.trim().length > 0);
+	};
+
 	const definitionToGitArgs = (
 		definition: GitResource,
 		resourcesDirectory: string,
@@ -29,7 +37,7 @@ export namespace Resources {
 		name: definition.name,
 		url: definition.url,
 		branch: definition.branch,
-		repoSubPath: definition.searchPath ?? '',
+		repoSubPaths: normalizeSearchPaths(definition),
 		resourcesDirectoryPath: resourcesDirectory,
 		specialAgentInstructions: definition.specialNotes ?? '',
 		quiet
@@ -45,8 +53,9 @@ export namespace Resources {
 	const loadLocalResource = (args: BtcaLocalResourceArgs): BtcaFsResource => ({
 		_tag: 'fs-based',
 		name: args.name,
+		fsName: resourceNameToKey(args.name),
 		type: 'local',
-		repoSubPath: '',
+		repoSubPaths: [],
 		specialAgentInstructions: args.specialAgentInstructions,
 		getAbsoluteDirectoryPath: async () => args.path
 	});

package/src/resources/types.ts

@@ -4,8 +4,9 @@ export const FS_RESOURCE_SYSTEM_NOTE =
 export type BtcaFsResource = {
 	readonly _tag: 'fs-based';
 	readonly name: string;
+	readonly fsName: string;
 	readonly type: 'git' | 'local';
-	readonly repoSubPath: string;
+	readonly repoSubPaths: readonly string[];
 	readonly specialAgentInstructions: string;
 	readonly getAbsoluteDirectoryPath: () => Promise<string>;
 };
@@ -15,7 +16,7 @@ export type BtcaGitResourceArgs = {
 	readonly name: string;
 	readonly url: string;
 	readonly branch: string;
-	readonly repoSubPath: string;
+	readonly repoSubPaths: readonly string[];
 	readonly resourcesDirectoryPath: string;
 	readonly specialAgentInstructions: string;
 	readonly quiet: boolean;

package/src/validation/index.ts

@@ -16,7 +16,7 @@
  * Resource name: must start with a letter, followed by alphanumeric and hyphens only.
  * This prevents path traversal (../), git option injection (-), and shell metacharacters.
  */
-const RESOURCE_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+const RESOURCE_NAME_REGEX = /^@?[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
 
 /**
  * Branch name: alphanumeric, forward slashes, dots, underscores, and hyphens.
@@ -59,8 +59,17 @@ export const LIMITS = {
 
 export type ValidationResult = { valid: true } | { valid: false; error: string };
 
+/**
+ * Validation result that includes a normalized value.
+ */
+export type ValidationResultWithValue<T> =
+	| { valid: true; value: T }
+	| { valid: false; error: string };
+
 const ok = (): ValidationResult => ({ valid: true });
+const okWithValue = <T>(value: T): ValidationResultWithValue<T> => ({ valid: true, value });
 const fail = (error: string): ValidationResult => ({ valid: false, error });
+const failWithValue = <T>(error: string): ValidationResultWithValue<T> => ({ valid: false, error });
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Validators
@@ -86,9 +95,18 @@ export const validateResourceName = (name: string): ValidationResult => {
 
 	if (!RESOURCE_NAME_REGEX.test(name)) {
 		return fail(
-			`Invalid resource name: "${name}". Must start with a letter and contain only alphanumeric characters and hyphens`
+			`Invalid resource name: "${name}". Must start with a letter or @ and contain only letters, numbers, ., _, -, and /`
 		);
 	}
+	if (name.includes('..')) {
+		return fail('Resource name must not contain ".."');
+	}
+	if (name.includes('//')) {
+		return fail('Resource name must not contain "//"');
+	}
+	if (name.endsWith('/')) {
+		return fail('Resource name must not end with "/"');
+	}
 
 	return ok();
 };
@@ -126,37 +144,84 @@ export const validateBranchName = (branch: string): ValidationResult => {
 	return ok();
 };
 
+/**
+ * Normalize a GitHub URL to its base repository format.
+ *
+ * Handles URLs like:
+ * - https://github.com/owner/repo/blob/main/README.md → https://github.com/owner/repo
+ * - https://github.com/owner/repo/tree/branch/path → https://github.com/owner/repo
+ * - https://github.com/owner/repo.git → https://github.com/owner/repo
+ * - https://github.com/owner/repo/ → https://github.com/owner/repo
+ *
+ * Non-GitHub URLs are returned unchanged.
+ */
+export const normalizeGitHubUrl = (url: string): string => {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return url; // Return as-is if not a valid URL
+	}
+
+	const hostname = parsed.hostname.toLowerCase();
+	if (hostname !== 'github.com') {
+		return url; // Non-GitHub URLs pass through unchanged
+	}
+
+	// Extract path segments, filtering out empty strings
+	const segments = parsed.pathname.split('/').filter((s) => s.length > 0);
+
+	// Need at least owner and repo
+	if (segments.length < 2) {
+		return url;
+	}
+
+	// Get owner and repo (first two segments)
+	const owner = segments[0];
+	let repo = segments[1]!;
+
+	// Remove .git suffix if present
+	if (repo.endsWith('.git')) {
+		repo = repo.slice(0, -4);
+	}
+
+	return `https://github.com/${owner}/${repo}`;
+};
+
 /**
  * Validate a git URL to prevent unsafe git operations.
+ * Returns the normalized URL on success.
  *
  * Requirements:
  * - Valid URL format
  * - HTTPS protocol only (rejects file://, git://, ssh://, ext::, etc.)
  * - No embedded credentials
  * - No localhost or private IP addresses
+ *
+ * For GitHub URLs, the URL is normalized to the base repository format.
  */
-export const validateGitUrl = (url: string): ValidationResult => {
+export const validateGitUrl = (url: string): ValidationResultWithValue<string> => {
 	if (!url || url.trim().length === 0) {
-		return fail('Git URL cannot be empty');
+		return failWithValue('Git URL cannot be empty');
 	}
 
 	let parsed: URL;
 	try {
 		parsed = new URL(url);
 	} catch {
-		return fail(`Invalid URL format: "${url}"`);
+		return failWithValue(`Invalid URL format: "${url}"`);
 	}
 
 	// Only allow HTTPS protocol
 	if (parsed.protocol !== 'https:') {
-		return fail(
+		return failWithValue(
 			`Invalid URL protocol: ${parsed.protocol}. Only HTTPS URLs are allowed for security reasons`
 		);
 	}
 
 	// Reject embedded credentials
 	if (parsed.username || parsed.password) {
-		return fail('URL must not contain embedded credentials');
+		return failWithValue('URL must not contain embedded credentials');
 	}
 
 	// Reject localhost and private IP addresses
@@ -170,10 +235,12 @@ export const validateGitUrl = (url: string): ValidationResult => {
 		hostname === '::1' ||
 		hostname === '0.0.0.0'
 	) {
-		return fail(`URL must not point to localhost or private IP addresses: ${hostname}`);
+		return failWithValue(`URL must not point to localhost or private IP addresses: ${hostname}`);
 	}
 
-	return ok();
+	// Normalize GitHub URLs
+	const normalizedUrl = normalizeGitHubUrl(url);
+	return okWithValue(normalizedUrl);
 };
 
 /**
@@ -213,6 +280,20 @@ export const validateSearchPath = (searchPath: string | undefined): ValidationRe
 	return ok();
 };
 
+export const validateSearchPaths = (
+	searchPaths: string[] | undefined
+): ValidationResult => {
+	if (!searchPaths) return ok();
+	if (searchPaths.length === 0) return fail('searchPaths must include at least one path');
+
+	for (const searchPath of searchPaths) {
+		const result = validateSearchPath(searchPath);
+		if (!result.valid) return result;
+	}
+
+	return ok();
+};
+
 /**
  * Validate a local file path.
  *
@@ -351,52 +432,89 @@ export const validateResourcesArray = (resources: string[] | undefined): Validat
 // Composite Validators
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Validated git resource with normalized URL.
+ */
+export interface ValidatedGitResource {
+	name: string;
+	url: string;
+	branch: string;
+	searchPath?: string;
+	searchPaths?: string[];
+	specialNotes?: string;
+}
+
+/**
+ * Validated local resource.
+ */
+export interface ValidatedLocalResource {
+	name: string;
+	path: string;
+	specialNotes?: string;
+}
+
 /**
  * Validate a complete git resource definition.
+ * Returns the resource with a normalized URL on success.
  */
 export const validateGitResource = (resource: {
 	name: string;
 	url: string;
 	branch: string;
 	searchPath?: string;
+	searchPaths?: string[];
 	specialNotes?: string;
-}): ValidationResult => {
+}): ValidationResultWithValue<ValidatedGitResource> => {
 	const nameResult = validateResourceName(resource.name);
-	if (!nameResult.valid) return nameResult;
+	if (!nameResult.valid) return failWithValue(nameResult.error);
 
 	const urlResult = validateGitUrl(resource.url);
-	if (!urlResult.valid) return urlResult;
+	if (!urlResult.valid) return failWithValue(urlResult.error);
 
 	const branchResult = validateBranchName(resource.branch);
-	if (!branchResult.valid) return branchResult;
+	if (!branchResult.valid) return failWithValue(branchResult.error);
 
 	const searchPathResult = validateSearchPath(resource.searchPath);
-	if (!searchPathResult.valid) return searchPathResult;
+	if (!searchPathResult.valid) return failWithValue(searchPathResult.error);
+	const searchPathsResult = validateSearchPaths(resource.searchPaths);
+	if (!searchPathsResult.valid) return failWithValue(searchPathsResult.error);
 
 	const notesResult = validateNotes(resource.specialNotes);
-	if (!notesResult.valid) return notesResult;
-
-	return ok();
+	if (!notesResult.valid) return failWithValue(notesResult.error);
+
+	return okWithValue({
+		name: resource.name,
+		url: urlResult.value, // Use the normalized URL
+		branch: resource.branch,
+		...(resource.searchPath && { searchPath: resource.searchPath }),
+		...(resource.searchPaths && { searchPaths: resource.searchPaths }),
+		...(resource.specialNotes && { specialNotes: resource.specialNotes })
+	});
 };
 
 /**
  * Validate a complete local resource definition.
+ * Returns the validated resource on success.
  */
 export const validateLocalResource = (resource: {
 	name: string;
 	path: string;
 	specialNotes?: string;
-}): ValidationResult => {
+}): ValidationResultWithValue<ValidatedLocalResource> => {
 	const nameResult = validateResourceName(resource.name);
-	if (!nameResult.valid) return nameResult;
+	if (!nameResult.valid) return failWithValue(nameResult.error);
 
 	const pathResult = validateLocalPath(resource.path);
-	if (!pathResult.valid) return pathResult;
+	if (!pathResult.valid) return failWithValue(pathResult.error);
 
 	const notesResult = validateNotes(resource.specialNotes);
-	if (!notesResult.valid) return notesResult;
+	if (!notesResult.valid) return failWithValue(notesResult.error);
 
-	return ok();
+	return okWithValue({
+		name: resource.name,
+		path: resource.path,
+		...(resource.specialNotes && { specialNotes: resource.specialNotes })
+	});
 };
 
 /**