Add structured project documentation

README.md

@@ -0,0 +1,80 @@
+# VirtualFS
+
+VirtualFS is a .NET library for composing multiple file-like data sources into one virtual hierarchy.
+
+The core model is:
+
+- every backend implements `IFileSystem`
+- a `RootFileSystem` mounts many backends under virtual paths
+- callers interact with virtual paths like `/assets/logo.png`
+- reads and writes are dispatched to the mounted backend that owns that path
+
+It behaves more like a small VFS layer than a thin `System.IO` wrapper.
+
+## Status
+
+The project currently targets:
+
+- `netstandard2.0`
+- `net472`
+- `net6.0`
+- `net8.0`
+- `net10.0`
+
+The test project targets `net10.0`.
+
+## Key Rules
+
+- paths are always rooted
+- `/foo/` is a directory
+- `/foo` is a file
+- trailing `/` defines directory vs file
+- path separator is always `/`
+- mounted filesystems can overlap
+- mount priority controls lookup order
+
+## Minimal Example
+
+```csharp
+using System.IO;
+using VirtualFS;
+using VirtualFS.Implementation;
+using VirtualFS.Memory;
+using VirtualFS.Physical;
+
+var root = new RootFileSystem();
+
+root.Mount(new PhysicalFileSystem(new DirectoryInfo("./content")), "/");
+root.Mount(new MemoryFileSystem { Priority = FileSystemMountPriority.High }, "/");
+
+root.Root.FileCreate("runtime.txt").WriteAllText("generated at runtime");
+
+foreach (var entry in root.Root.GetEntries())
+{
+    Console.WriteLine($"{entry.FullPath} readonly={entry.IsReadOnly}");
+}
+```
+
+## Documentation
+
+Detailed documentation is split into the `docs/` folder:
+
+- [Documentation Index](./docs/README.md)
+- [Architecture](./docs/architecture.md)
+- [Usage](./docs/usage.md)
+- [Backends](./docs/backends.md)
+- [Development](./docs/development.md)
+
+## Build and Test
+
+The repository includes a Docker-based build/test flow using the official .NET 10 SDK image.
+
+```bash
+docker build --target test -t virtualfs:test .
+```
+
+The repository CI runs the same Docker target on pushes and pull requests.
+
+## License
+
+The project metadata declares the MIT license.