Add structured project documentation

docs/development.md

@@ -0,0 +1,112 @@
+# Development
+
+## Repository Layout
+
+Main folders:
+
+- `VirtualFS/`
+- `VirtualFS/Implementation/`
+- `VirtualFS/Physical/`
+- `VirtualFS/Memory/`
+- `VirtualFS/Compressed/`
+- `VirtualFS/EmbeddedResource/`
+- `VirtualFS.Tests/`
+
+Important files:
+
+- `VirtualFS.sln`
+- `VirtualFS/VirtualFS.csproj`
+- `VirtualFS.Tests/VirtualFS.Tests.csproj`
+- `Dockerfile`
+- `.github/workflows/docker.yml`
+
+## Target Frameworks
+
+Library targets:
+
+- `netstandard2.0`
+- `net472`
+- `net6.0`
+- `net8.0`
+- `net10.0`
+
+Tests target:
+
+- `net10.0`
+
+## Build and Test
+
+The repository uses a Docker-based build/test flow with the official .NET 10 SDK image.
+
+Run the full containerized verification:
+
+```bash
+docker build --target test -t virtualfs:test .
+```
+
+This performs:
+
+- restore
+- build
+- test
+
+## Test Stack
+
+The test project currently uses:
+
+- xUnit v3
+- `Microsoft.NET.Test.Sdk`
+- `coverlet.collector`
+
+## CI
+
+The repository workflow is:
+
+- `.github/workflows/docker.yml`
+
+It runs the same Docker build/test path on:
+
+- pushes
+- pull requests
+
+## Adding a New Backend
+
+The expected implementation approach is:
+
+1. derive from `BaseFileSystem`
+2. implement the abstract operations required by `IFileSystem`
+3. return `VirtualStream` for open file handles
+4. populate entry metadata consistently
+5. respect read-only semantics
+6. add focused tests for backend-specific behavior
+
+Backend responsibilities generally include:
+
+- existence checks
+- metadata lookup
+- enumeration
+- create/delete
+- read/write stream opening
+- rename/move/copy where backend-specific optimization is useful
+
+## Design Characteristics to Keep in Mind
+
+These are important when changing the library:
+
+- path semantics are custom and intentionally `/`-based
+- directory vs file is determined by trailing slash
+- `RootFileSystem` composes mounted backends but is not itself writable
+- `Entry.Path` is backend-local, `Entry.FullPath` is root-visible
+- `EntryRealPath` may be unavailable for some backends
+- unmounting depends on `IsBusy`
+- generic copy/move logic may be correct but not optimal for remote backends
+
+## Documentation Structure
+
+Current documentation:
+
+- top-level overview: `README.md`
+- architecture details: `docs/architecture.md`
+- usage examples: `docs/usage.md`
+- backend summary: `docs/backends.md`
+- development notes: `docs/development.md`