Scope file systems to the path argument rather than CWD

RealRead/RealWrite are pre-allocated singletons scoped to
Paths.WorkingDirectoryRoot (the CWD git root). Commands that accept an
explicit --path or --output argument may target a repo outside that root,
which would cause ScopedFileSystemException.

Add FileSystemFactory.ForPath(string? path) and ForPathWrite(string? path,
string? output) that derive the scope root dynamically by walking up from
the given path to find its .git boundary. Both fall back to RealRead/RealWrite
when no path is provided (CWD-relative operation). ForPathWrite also adds
the output directory as an extra scope root when it falls outside the git root.

Update all commands that accept --path/--output to use these:
IndexCommand, IsolatedBuildCommand, ServeCommand, FormatCommand,
MoveCommand, DiffCommands, InMemoryBuildState, StaticWebHost.

Commands that always operate relative to CWD (assembler, codex, changelog)
continue using RealRead since their scope is determined by assembler config
or git context, not an arbitrary user-provided path.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: Mpdreamz

src/Elastic.Documentation.Configuration/FileSystemFactory.cs

@@ -97,4 +97,66 @@ public static ScopedFileSystem WrapToRead(IFileSystem inner, IEnumerable<string>
 	/// <summary>Wraps <paramref name="inner"/> with write workspace options (.git not allowed).</summary>
 	public static ScopedFileSystem WrapToWrite(IFileSystem inner) =>
 		new(inner, WriteOptions);
+
+	/// <summary>
+	/// Creates a read <see cref="ScopedFileSystem"/> scoped to the git root of
+	/// <paramref name="path"/>. Falls back to <see cref="RealRead"/> when <paramref name="path"/>
+	/// is <see langword="null"/>. Use in commands that accept an explicit <c>--path</c> argument.
+	/// </summary>
+	public static ScopedFileSystem ForPath(string? path)
+	{
+		if (path is null)
+			return RealRead;
+		var root = FindGitRoot(path);
+		return new ScopedFileSystem(new FileSystem(), new ScopedFileSystemOptions([root, Paths.ApplicationData.FullName])
+		{
+			AllowedHiddenFolderNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { ".git", ".artifacts" },
+			AllowedHiddenFileNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { ".git", ".doc.state" }
+		});
+	}
+
+	/// <summary>
+	/// Creates a write <see cref="ScopedFileSystem"/> scoped to the git root of
+	/// <paramref name="path"/> (and <paramref name="output"/> if it falls outside that root).
+	/// Falls back to <see cref="RealWrite"/> when both are <see langword="null"/>.
+	/// Use in commands that accept explicit <c>--path</c> and/or <c>--output</c> arguments.
+	/// </summary>
+	public static ScopedFileSystem ForPathWrite(string? path, string? output = null)
+	{
+		if (path is null && output is null)
+			return RealWrite;
+
+		var gitRoot = path is not null ? FindGitRoot(path) : Paths.WorkingDirectoryRoot.FullName;
+		var roots = new List<string> { gitRoot, Paths.ApplicationData.FullName };
+
+		if (output is not null)
+		{
+			var absOutput = Path.IsPathRooted(output) ? output : Path.GetFullPath(output);
+			if (!absOutput.StartsWith(gitRoot, StringComparison.OrdinalIgnoreCase))
+				roots.Add(absOutput);
+		}
+
+		return new ScopedFileSystem(new FileSystem(), new ScopedFileSystemOptions([.. roots])
+		{
+			AllowedHiddenFolderNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { ".artifacts" },
+			AllowedHiddenFileNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { ".doc.state" }
+		});
+	}
+
+	// Walks up from startPath to find the nearest .git directory or file (worktree support).
+	// Uses System.IO directly — acceptable bootstrap, same pattern as Paths.DetermineWorkingDirectoryRoot.
+	private static string FindGitRoot(string startPath)
+	{
+		var resolved = Path.IsPathRooted(startPath) ? startPath : Path.GetFullPath(startPath);
+		var dir = Directory.Exists(resolved)
+			? new DirectoryInfo(resolved)
+			: new DirectoryInfo(Path.GetDirectoryName(resolved) ?? resolved);
+		while (dir != null)
+		{
+			if (dir.GetDirectories(".git").Length > 0 || dir.GetFiles(".git").Length > 0)
+				return dir.FullName;
+			dir = dir.Parent;
+		}
+		return Path.GetPathRoot(resolved) ?? resolved;
+	}
 }

src/tooling/docs-builder/Commands/DiffCommands.cs

@@ -29,7 +29,7 @@ public async Task<int> ValidateRedirects(string? path = null, Cancel ctx = defau
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new LocalChangeTrackingService(logFactory, configurationContext);
-		var fs = FileSystemFactory.RealRead;
+		var fs = FileSystemFactory.ForPath(path);
 
 		serviceInvoker.AddCommand(service, (path, fs),
 				async static (s, collector, state, _) => await s.ValidateRedirects(collector, state.path, state.fs)

src/tooling/docs-builder/Commands/FormatCommand.cs

@@ -43,7 +43,7 @@ public async Task<int> Format(
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new FormatService(logFactory, configurationContext);
-		var fs = FileSystemFactory.RealRead;
+		var fs = FileSystemFactory.ForPath(path);
 
 		serviceInvoker.AddCommand(service, (path, check, fs),
 			async static (s, collector, state, ctx) => await s.Format(collector, state.path, state.check, state.fs, ctx)

src/tooling/docs-builder/Commands/IndexCommand.cs

@@ -86,7 +86,7 @@ public async Task<int> Index(
 	)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
-		var fs = FileSystemFactory.RealRead;
+		var fs = FileSystemFactory.ForPath(path);
 		var service = new IsolatedIndexService(logFactory, configurationContext, githubActionsService, environmentVariables);
 		var state = (fs, path,
 				// endpoint options

src/tooling/docs-builder/Commands/IsolatedBuildCommand.cs

@@ -62,9 +62,9 @@ public async Task<int> Build(
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new IsolatedBuildService(logFactory, configurationContext, githubActionsService, environmentVariables);
-		var readFs = inMemory ? FileSystemFactory.InMemory() : FileSystemFactory.RealRead;
+		var readFs = inMemory ? FileSystemFactory.InMemory() : FileSystemFactory.ForPath(path);
 		// For real builds supply an explicit write FS without .git access; for in-memory null falls back to readFs
-		var writeFs = inMemory ? null : FileSystemFactory.RealWrite;
+		var writeFs = inMemory ? null : FileSystemFactory.ForPathWrite(path, output);
 		var strictCommand = service.IsStrict(strict);
 
 		serviceInvoker.AddCommand(service,

src/tooling/docs-builder/Commands/MoveCommand.cs

@@ -38,7 +38,7 @@ public async Task<int> Move(
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new MoveFileService(logFactory, configurationContext);
-		var fs = FileSystemFactory.RealRead;
+		var fs = FileSystemFactory.ForPath(path);
 
 		serviceInvoker.AddCommand(service, (source, target, dryRun, path, fs),
 			async static (s, collector, state, ctx) => await s.Move(collector, state.source, state.target, state.dryRun, state.path, state.fs, ctx)

src/tooling/docs-builder/Commands/ServeCommand.cs

@@ -27,7 +27,7 @@ internal sealed class ServeCommand(ILoggerFactory logFactory, IConfigurationCont
 	[Command("")]
 	public async Task Serve(string? path = null, int port = 3000, bool watch = false, Cancel ctx = default)
 	{
-		var host = new DocumentationWebHost(logFactory, path, port, FileSystemFactory.RealRead, FileSystemFactory.InMemory(), configurationContext, watch);
+		var host = new DocumentationWebHost(logFactory, path, port, FileSystemFactory.ForPath(path), FileSystemFactory.InMemory(), configurationContext, watch);
 		await host.RunAsync(ctx);
 		_logger.LogInformation("Find your documentation at http://localhost:{Port}/{Path}", port,
 			host.GeneratorState.Generator.DocumentationSet.FirstInterestingUrl.TrimStart('/')

src/tooling/docs-builder/Http/InMemoryBuildState.cs

@@ -169,7 +169,7 @@ private async Task ExecuteBuildAsync(string sourcePath, Cancel ct)
 			// Create a diagnostics collector that streams to our channel
 			var streamingCollector = new StreamingDiagnosticsCollector(_loggerFactory, this);
 
-			var readFs = FileSystemFactory.RealRead;
+			var readFs = FileSystemFactory.ForPath(sourcePath);
 			var service = new IsolatedBuildService(_loggerFactory, _configurationContext, new NullCoreService(), SystemEnvironmentVariables.Instance);
 
 			_logger.LogInformation("Starting in-memory validation build for {Path}", sourcePath);

src/tooling/docs-builder/Http/StaticWebHost.cs

@@ -25,7 +25,7 @@ public class StaticWebHost
 	public StaticWebHost(int port, string? path)
 	{
 		_contentRoot = path ?? Path.Join(Paths.WorkingDirectoryRoot.FullName, ".artifacts", "assembly");
-		var fs = FileSystemFactory.RealRead;
+		var fs = FileSystemFactory.ForPath(path);
 		var dir = fs.DirectoryInfo.New(_contentRoot);
 		if (!dir.Exists)
 			throw new Exception($"Can not serve empty directory: {_contentRoot}");