docs: add FS and FileService info

docs/StaticFileService.md

@@ -0,0 +1,84 @@
+# StaticFileService
+
+Serves static files from the device's LittleFS filesystem over HTTP.
+
+## Overview
+
+- Service name: `StaticFileService`
+- Mounts: LittleFS at startup
+- Endpoints:
+  - GET / → serves /index.html
+  - GET /* → serves any file under LittleFS by path
+
+Files are looked up relative to the filesystem root. If a requested path is empty or `/`, it falls back to `index.html`. Unknown paths return 404; a helper exists to fall back to `index.html` for SPA routing if desired.
+
+## Content types
+
+Determined by filename extension:
+
+- .html, .htm → text/html
+- .css → text/css
+- .js → application/javascript
+- .json → application/json
+- .png → image/png
+- .jpg, .jpeg → image/jpeg
+- .gif → image/gif
+- .svg → image/svg+xml
+- .ico → image/x-icon
+- default → application/octet-stream
+
+## Building and uploading the filesystem
+
+Place your web assets under the `data/` folder at the project root. The build system packages `data/` into a LittleFS image matching the environment's flash layout.
+
+### Upload via PlatformIO
+
+```bash
+# Build and upload filesystem for esp01_1m
+pio run -e esp01_1m -t uploadfs
+
+# Build and upload filesystem for d1_mini
+pio run -e d1_mini -t uploadfs
+```
+
+### Manual image build (optional)
+
+There are helper commands in `ctl.sh` if you need to build and flash the FS image manually:
+
+```bash
+# Build image from ./data into littlefs.bin
+./ctl.sh mkfs
+
+# Flash image at preconfigured offset
+./ctl.sh flashfs
+```
+
+Note: Offsets and sizes must match the environment's ldscript. The project defaults are:
+
+- esp01_1m: ldscript `eagle.flash.1m64.ld` (64KB FS)
+- d1_mini: ldscript `eagle.flash.4m1m.ld` (1MB FS)
+
+See `docs/Development.md` for details on filesystem and ldscript mapping.
+
+## Enabling the service
+
+`StaticFileService` is registered as a core service in the framework and enabled by default:
+
+```cpp
+// part of Spore::registerCoreServices()
+auto staticFileService = std::make_shared<StaticFileService>(ctx, apiServer);
+services.push_back(staticFileService);
+```
+
+If you maintain a custom build without the default services, ensure you instantiate and add the service before starting the API server.
+
+## Routing notes
+
+- Place your SPA assets in `data/` and reference paths relatively.
+- To support client-side routing, you can adapt `handleNotFound` to always serve `/index.html` for unknown paths.
+
+## Troubleshooting
+
+- "LittleFS Mount Failed": Ensure `board_build.filesystem = littlefs` is set and the ldscript provides a filesystem region.
+- 404 for known files: Confirm the file exists under `data/` and was uploaded (`pio run -t uploadfs`).
+- Incorrect MIME type: Add the extension mapping to `getContentType()` if using custom extensions.